How to integrate PayPal
This is a step-by-step guide on how to integrate PayPal with DEUNA, either via Widget or API.
Overview
PayPal
PayPal is a online payment method that follows you wherever you go. Pay any way you want. Link your credit cards to your PayPal Digital wallet, and when you want to pay, simply log in with your username and password and pick which one you want to use.
Payment processes
- Checkout
PayPal Checkout is a one-time payment checkout experience that gives you more control over the entire checkout process. It offers a streamlined checkout flow that keeps customers local to your website during the payment authorization process. Unlike the Vault flow, Checkout does not provide the ability to store a customer's PayPal account.
PayPal Checkout only occurs for unauthenticated or new users and therefore, as they do not have an existing identity, they do not yet have the ability to select payment installments. - Vault
PayPal Vault will allow you to charge the account in the future without requiring your customer to be present during the transaction or re-authenticate with PayPal when they are present during the transaction.
PayPal Vault is available to authenticated users and they have the ability to select payment installments if the merchant allows or requires it.
Integration steps
Environments:
- Sandbox: https://api.sandbox.deuna.io
- Production: https://api.deuna.io
Postman Collection:
Set up payment processor
-
The PayPal payment processor configuration can be done from the DEUNA Admin, in the Connections section:
-
Find PayPal Wallet Processor:
-
Enter PayPal business account credentials:
The Vaulting checkbox allows authenticated users to save their account for quick future purchases without requiring authentication in PayPal.
Create order
To make a purchase, the merchant must first create a DEUNA order. The API will return the order_token, which will be used in the following steps. You can follow the next guide to Create Order.
-
Required fields:
Field Description Value order.store_codeUnique code of store allorder.payment_methodDEUNA payment method type. walletorder.items_total_amountTotal amount of items without taxes nor discounts. 2000
-
Considerations:
- About
order.itemswe need considerate:total_amount.original_amountmust beunit_price.amount * quantity.total_amount.amountmust be((unit_price.amount + tax_amount.amount) * quantity) - total_amount.total_discounts.total_amount.total_discountsis the total value of discounts for the quantity of items.
order.items_total_amountis the sum of the items unit prices, this amount added to theorder.total_tax_amountand minusorder.discount_amountmust match with theorder.total_amount.order.sub_totalis the sum of the items unit price minus discounts, this amount added to theorder.total_tax_amountmust match theorder.total_amount.
- About
-
Request Example:
{ "order": { "order_id": "{{$randomUUID}}", // this can be updated using the "1.2 Update order" "store_code": "all", // very important is "all" "payment_method": "wallet", // required for PayPal "currency": "MXN", "items_total_amount": 1, // required for PayPal "tax_amount": 107035, "sub_total": 1529068, // required for PayPal "shipping_amount": 0, "shipping_tax_amount": 0, "total_tax_amount": 107035, "total_amount": 1636103, "discounts": [], "items": [ { "id": "{{$randomUUID}}", "name": "GeForce RTX 5070 Ti", "description": "GeForce RTX 5070 Ti Graphic Card", "total_amount": { "original_amount": 1529068, "amount": 1636103, "total_discount": 0, "currency": "MXN", "currency_symbol": "$" }, "unit_price": { "amount": 1529068, "currency": "MXN", "currency_symbol": "$" }, "tax_amount": { "amount": 107035, "currency": "MXN", "currency_symbol": "$" }, "quantity": 1, "image_url": "https://radargit.com/wp-content/uploads/2025/01/geforce-rtx-5070-ti-og-image-860x452.webp", "taxable": true } ], "shipping_address": { "id": "{{$randomInt}}", "first_name": "John", "last_name": "Doe", "email": "[email protected]", "identity_document": "1234567890", "address1": "Congreso 103", "address2": "", "zipcode": "14000", "city": "Mexico City", "state_name": "FD", "country_code": "MX", "phone": "+525534557939", "lat": 19.280599, "lng": -99.168195, "additional_description": "confirm", "address_type": "home" }, "billing_address": { "id": "{{$randomInt}}", "first_name": "John", "last_name": "Doe", "email": "[email protected]", "identity_document": "1234567890", "address1": "Congreso 103", "address2": "", "zipcode": "14000", "city": "Mexico City", "state_name": "FD", "country_code": "MX", "phone": "+525534557939", "lat": 19.280599, "lng": -99.168195, "additional_description": "confirm", "address_type": "home" }, "metadata": { "highrisk_txn_flag": 1, // 1 | 0 "vertical": "Retail", // 1 | 0 "cd_string_one": 1 // 1 | 0 }, "browser_details": { "screen_height": 1000, "screen_width": 2000 } } } -
Response:
{ "token": "2f06178f-797a-4765-8ddd-c2fa213bfda9", "order_type": "DEUNA_CHECKOUT", "order": { "order_id": "a47c0adf-d000-46e6-97a1-9c839b6e7bae", "store_code": "all", "currency": "MXN", "tax_amount": 107035, "display_tax_amount": "MXN 1,070.35", "shipping_amount": 0, "display_shipping_amount": "MXN 0.00", "items_total_amount": 1, "display_items_total_amount": "MXN 0.01", "sub_total": 1529068, "display_sub_total": "MXN 15,290.68", "total_amount": 1636103, "display_total_amount": "MXN 16,361.03", "items": [ { "id": "8a2c1557-2064-41f7-b7af-522915bd37f0", "name": "GeForce RTX 5070 Ti", "description": "GeForce RTX 5070 Ti Graphic Card", "options": "", "total_amount": { "amount": 1636103, "original_amount": 1529068, "display_amount": "MXN 16,361.03", "display_original_amount": "MXN 15,290.68", "currency": "MXN", "currency_symbol": "$", "total_discount": 0, "display_total_discount": "MXN 0.00" }, "unit_price": { "amount": 1529068, "display_amount": "MXN 15,290.68", "currency": "MXN", "currency_symbol": "$" }, "tax_amount": { "amount": 107035, "display_amount": "MXN 1,070.35", "currency": "MXN", "currency_symbol": "$" }, "quantity": 1, "uom": "", "upc": "", "sku": "", "isbn": "", "brand": "", "manufacturer": "", "category": "", "color": "", "size": "", "weight": { "weight": 0, "unit": "" }, "image_url": "https://radargit.com/wp-content/uploads/2025/01/geforce-rtx-5070-ti-og-image-860x452.webp", "details_url": "", "type": "", "taxable": true, "discounts": [], "included_in_subscription": false, "item_details": [] } ], "discounts": [], "shipping_address": { "id": 980, "user_id": "", "first_name": "John", "last_name": "Doe", "phone": "+525534557939", "identity_document": "1234567890", "lat": 19.280599, "lng": -99.168195, "address1": "Congreso 103", "address2": "", "city": "Mexico City", "zipcode": "14000", "state_name": "FD", "country_code": "MX", "additional_description": "confirm", "address_type": "home", "is_default": false, "created_at": "2025-02-27T02:52:39Z", "updated_at": "2025-02-27T02:52:39Z", "identity_document_type": "", "email": "[email protected]", "state_code": "", "country": "MX" }, "shipping_options": { "type": "", "details": { "store_name": "", "address": "", "address_coordinates": { "lat": 0, "lng": 0 }, "contact": { "name": "", "phone": "" }, "additional_details": { "pickup_time": "0001-01-01T00:00:00Z", "stock_location": "" } } }, "user_instructions": "", "metadata": { "cd_string_one": 1, "highrisk_txn_flag": 1, "vertical": "Retail" }, "status": "pending", "payment": { "data": { "amount": { "amount": 0, "currency": "" }, "metadata": {}, "from_card": { "card_brand": "", "first_six": "", "last_four": "", "bank_name": "", "country_iso": "", "credential_source": "", "expiry_month": "", "expiry_year": "" }, "updated_at": "0001-01-01 00:00:00 +0000 UTC", "method_type": "", "merchant": { "store_code": "", "id": "", "affiliation_code": "", "mcc": "" }, "created_at": "0001-01-01 00:00:00 +0000 UTC", "id": "", "processor": "", "customer": { "email": "", "id": "", "first_name": "", "last_name": "" }, "status": "", "reason": "", "external_transaction_id": "", "merchant_payment_processor_name": "", "authorization_code": "", "installment_interest_calculations": null, "three_ds_details": {}, "merchant_payment_processor_id": "" } }, "gift_card": [], "redirect_url": "", "webhook_urls": null, "total_discount": 0, "display_total_discount": "MXN 0.00", "shipping": { "original_amount": 0, "total_discount": 0, "discounts": [] }, "cash_change": 0, "shipping_method": { "code": "", "name": "", "min_delivery_date": "", "max_delivery_date": "", "cost": 0, "display_cost": "", "tax_amount": 0, "display_tax_amount": "", "scheduler": [] }, "shipping_methods": [], "timezone": "", "scheduled_at": "", "billing_address": { "id": 341, "user_id": "", "first_name": "John", "last_name": "Doe", "phone": "+525534557939", "identity_document": "1234567890", "lat": 19.280599, "lng": -99.168195, "address1": "Congreso 103", "address2": "", "city": "Mexico City", "zipcode": "14000", "state_name": "FD", "country_code": "MX", "additional_description": "confirm", "address_type": "home", "is_default": false, "created_at": "2025-02-27T02:52:39Z", "updated_at": "2025-02-27T02:52:39Z", "email": "[email protected]", "identity_document_type": "", "country": "" }, "payment_link": "", "display_shipping_tax_amount": "MXN 0.00", "display_total_tax_amount": "MXN 1,070.35", "shipping_tax_amount": 0, "total_tax_amount": 107035, "user_id": "", "include_payment_options": [], "redirect_urls": { "success": "", "pending": "", "error": "", "fallback": "", "close": "" }, "created_at": "2025-02-27 02:52:39.507675476 +0000 UTC", "updated_at": "", "payer_info": null, "discount_amount": 0, "shipping_discount_amount": 0, "device_fingerprint": "", "expired_at": "", "version": "0", "fraud": null, "total_interest_amount": 0, "display_total_interest_amount": "MXN 0.00", "payment_method": "", "token": "", "statement_descriptor": "", "browser_details": { "screen_height": 1000, "screen_width": 2000, "user_agent": "", "ip_address": "", "color_depth": 0, "java_enabled": false, "java_script_enabled": false, "language": "", "time_zone_offset": 0, "accept_header": "" }, "callback_urls": null }, "custom_fields": [], "checkout_modules": [] }
Integrate by Widget
Payment flows
-
Express
The express flow allows the user to complete their payment in the shortest possible time. Once the user gives their consent to save their PayPal account, the payment will be made automatically and with a single click.
The express flow will be initialized when the widget detects a single payment method experience, i.e. PayPal only.
-
New/Guest user Vaulting disabled
The guest flow is defined for new users, registered users who are not authenticated or when the merchant has disabled the Vaulting feature. In this case, the Checkout payment process will be initialized, where the user will enter their PayPal account to make the payment but it will not be saved.
If the user is new, their data will be registered so that they can authenticate themselves for a future purchase and save their PayPal account for future payments.
-
Authenticated user without PayPal account saved
If the user is logged in but does not have a PayPal account saved, the Vaulting payment process will be initiated and the user will be redirected to the PayPal site where they will make the payment and give their consent to save their account and use it for future purchases. -
Authenticated user with PayPal account saved
If the user has authenticated and already has a PayPal account saved, the payment will be processed immediately because they have previously given their consent.
-
-
General
The general flow is enabled when the widget detects an experience with multiple payment methods.
In this flow, the user will have a greater role because they will be able to manage their accounts, that is, they will be able to add multiple accounts or delete one that they no longer use. In this flow, authenticated users also have the possibility to select payment installments depending on whether the merchant requires or allows them.-
New/Guest user or Vaulting disabled
When the user is not authenticated, is new or the merchant has disabled the Vaulting feature, clicking the PayPal button will initiated the Checkout payment process where the user must authenticate themselves in PayPal and make the payment. In this process the account will not be saved because there is no previous identification of the user, but their data will already be registered (if they are new) so that in a future purchase they will have the possibility of authenticating themselves and giving consent to save their PayPal account.
- Purchase flow
-
Authenticated user without PayPal accounts saved
When the user has authenticated and has no saved accounts, by pressing the PayPal button the Vaulting payment process will be initiated and the user will be redirected to the PayPal site where they will make the payment and give their consent to save their account and use it for future transactions.
If the merchant requires payment installments, the user will have to select them after authorizing the payment in PayPal.- View of account with required installments
Pending...
- View of account with required installments
-
Authenticated user with PayPal accounts saved
If the user is logged in and has saved PayPal accounts, they will be able to select the account they will use to make the payment, as well as delete any accounts they no longer wish to use or save a new one.
If the merchant offers payment installments, these will be displayed with the account selected for payment and if the user wants to use a new PayPal account, they will have to select the installments after authorizing the payment in PayPal.-
Single account view
-
Multiple accounts view
-
Purchase flow
-
-
Integrate by API
Once we have the order_token, we must do the following:
Create User
Create an user with DEUNA in order to get the authorization token to perform the purchase later. This API will return back a User's token which will be required to follow the next steps.
We recommend to use the OTP to get a new token each time your customer confirms through the SMS or Email the code. Also, you can use an External Authentication login to manage the user auth tokens by your own without request them the OTP. Talked to your Sales Engineer for further guidance.
To create a user, follow the API Reference. In case the email used already exists, the API will return the message user already exists, so you can proceed to Request the OTP and then, Login with the OTP to obtain a fresh user token and proceed with the purchase.
Get Payment Methods
We must check the payment methods to obtain the PayPal Wallet configuration. You can follow this guide.
-
Payload
curl --location '{{base_url}}/merchants/orders/{{order_token}}/payments-methods' \ --header 'x-api-key: {{merchant_private_key}}' \ --header 'Authorization: Bearer {{user_token}}' -
Response
{ "data": [ { "enabled": true, "method_type": "wallet", "processor_name": "paypal_wallet", // PayPal Wallet identifier "exclude_cvv": false, "stored_payment_methods": [ { "payment_method": "adb1ef51-e073-49f5-ba3b-a7e42344fd15", "account_identifier": "[email protected]" } ], "id": "58745b8e-7127-44ea-84ef-656b3ffc611b", // Payment method ID "authorization": { "required": true, // true | false "flow": "consent" } } ] }
Purchase flow
Depending on the response obtained from Get Payment Methods, we can follow the following flows to complete a purchase:
-
Without Vaulting
This is the flow to follow when tokenization of a PayPal account is not required to complete the purchase.
The response from Get Payment Methods would be as follows:
{ "data": [ { "enabled": true, "method_type": "wallet", "processor_name": "paypal_wallet", // PayPal Wallet identifier "exclude_cvv": false, "stored_payment_methods": [], "id": "58745b8e-7127-44ea-84ef-656b3ffc611b", // Payment method ID "authorization": { "required": false, "flow": "consent" } } ] }In this flow, we must do the following:
-
Perform the Purchase
-
To make a Purchase V1, you can refer to the following guide. Here is a list of required fields for PayPal Wallet:
Field Description Value specific_fields.callbacks.on_successRedirect URL after authorizing the purchase with your PayPal Wallet account. https://example.com/method_typeDEUNA payment method type. walletprocessor_namePayPal Wallet payment method identifier. paypal_walletPayload
{ "token": "{{order-token}}", "method_type": "wallet", // required for PayPal Wallet "processor_name": "paypal_wallet", // required for PayPal Wallet "email": "[email protected]", "device_id": "xxxxxxx", // PayPal device ID, used in STC "specific_fields": { "callbacks": { "on_success": "https://example.com" // required for PayPal Wallet } } } -
To make a Purchase V2, you can refer to the following guide. Here is a list of required fields for PayPal Wallet:
Field Description Value order.callback_urls.on_successRedirect URL after authorizing the purchase with your PayPal Wallet account. https://example.com/payment_source.method_typeDEUNA payment method type. walletpayment_source.processorPayPal Wallet payment method identifier. paypal_walletPayload
{ "order_type": "DEUNA_CHECKOUT", "order_token": "{{order-token}}", "order": { "callback_urls": { "on_success": "https://example.com" // required for PayPal Wallet } }, "payer_info": { "email": "[email protected]" }, "payment_source": { "method_type": "wallet", // required for PayPal Wallet "processor": "paypal_wallet" // required for PayPal Wallet }, "anti_fraud_info": { "device": { "id": "xxxxxxx" // PayPal device ID, used in STC } } }
Response
{ "order": { "order_id": "620bbbf4-1f08-4cda-8609-dade541cb80e", "store_code": "all", "currency": "MXN", "tax_amount": 0, "display_tax_amount": "", "shipping_amount": 0, "display_shipping_amount": "MXN 0.00", "items_total_amount": 2175, "display_items_total_amount": "MXN 21.75", "sub_total": 2075, "display_sub_total": "MXN 20.75", "total_amount": 2190, "display_total_amount": "MXN 21.90", "items": [ { "id": "849fd015-2e1b-4ccc-a00c-aacbefeb71c8", "name": "Papas", "description": "Papas fritas con paprica", "options": "", "total_amount": { "amount": 2100, "original_amount": 2100, "display_amount": "MXN 21.00", "display_original_amount": "MXN 21.00", "currency": "MXN", "currency_symbol": "$", "total_discount": 100, "display_total_discount": "MXN 1.00" }, "unit_price": { "amount": 1050, "display_amount": "MXN 10.50", "currency": "MXN", "currency_symbol": "$" }, "tax_amount": { "amount": 50, "display_amount": "MXN 0.50", "currency": "MXN", "currency_symbol": "$" }, "quantity": 2, "uom": "", "upc": "", "sku": "", "isbn": "", "brand": "", "manufacturer": "", "category": "", "color": "", "size": "", "weight": { "weight": 0, "unit": "" }, "image_url": "https://media-cdn.tripadvisor.com/media/photo-s/1a/e2/c6/68/porcion-de-papas-a-la.jpg", "details_url": "", "type": "", "taxable": true, "discounts": [], "included_in_subscription": false, "item_details": [] }, { "id": "c871341d-317b-4fdb-9d72-b55e55958633", "name": "Refresco", "description": "Coca-cola Sprite", "options": "", "total_amount": { "amount": 90, "original_amount": 75, "display_amount": "MXN 0.90", "display_original_amount": "MXN 0.75", "currency": "MXN", "currency_symbol": "$", "total_discount": 0, "display_total_discount": "MXN 0.00" }, "unit_price": { "amount": 75, "display_amount": "MXN 0.75", "currency": "MXN", "currency_symbol": "$" }, "tax_amount": { "amount": 15, "display_amount": "MXN 0.15", "currency": "MXN", "currency_symbol": "$" }, "quantity": 1, "uom": "", "upc": "", "sku": "", "isbn": "", "brand": "", "manufacturer": "", "category": "", "color": "", "size": "", "weight": { "weight": 0, "unit": "" }, "image_url": "https://media-cdn.tripadvisor.com/media/photo-s/1a/e2/c6/68/porcion-de-papas-a-la.jpg", "details_url": "", "type": "", "taxable": true, "discounts": [], "included_in_subscription": false, "item_details": [] } ], "discounts": [], "shipping_address": { "id": 762, "user_id": "", "first_name": "Pablo", "last_name": "Murillo", "phone": "+551146733466", "identity_document": "", "lat": -22.943934, "lng": -43.182984, "address1": "Jose luis lagrange 3, 12", "address2": "Polanco I Sección", "city": "MIGUEL HIDALGO", "zipcode": "11510", "state_name": "CIUDAD DE MÉXICO", "country_code": "MX", "additional_description": "confirmar", "address_type": "home", "is_default": false, "created_at": "2025-02-26T21:38:07Z", "updated_at": "2025-02-26T21:38:07Z", "identity_document_type": "", "email": "[email protected]", "state_code": "", "country": "MX" }, "shipping_options": null, "user_instructions": "", "metadata": { "cd_string_one": 1, "highrisk_txn_flag": 1, "vertical": "Retail" }, "status": "pending", "payment": { "data": { "amount": { "amount": 2190, "currency": "MXN" }, "metadata": { "authorization_code": "", "external_transaction_id": "6L9248503S6803027" }, "from_card": { "card_brand": "", "first_six": "", "last_four": "", "bank_name": "", "country_iso": "", "credential_source": "", "expiry_month": "", "expiry_year": "" }, "updated_at": "2025-02-26 21:38:12.748800962 +0000 UTC", "method_type": "wallet", "merchant": { "store_code": "all", "id": "2a18bdc9-d617-45cc-b718-838451dcf33a", "affiliation_code": "", "mcc": "" }, "created_at": "2025-02-26 21:38:12.747998969 +0000 UTC", "id": "620bbbf4-1f08-4cda-8609-dade541cb80e", "processor": "paypal_wallet", "customer": { "email": "[email protected]", "id": "9d920735-c3b1-4908-aba2-762d86fda7e0", "first_name": "", "last_name": "" }, "status": "pending", "reason": "", "external_transaction_id": "6L9248503S6803027", "merchant_payment_processor_name": "", "authorization_code": "", "installment_interest_calculations": null, "next_action": { "action": "authorization_wallet", "url": "", "authorization_wallet": { "token": "6L9248503S6803027", "redirect_url": "https://www.sandbox.paypal.com/checkoutnow?token=6L9248503S6803027" } }, "merchant_payment_processor_id": "" } }, "gift_card": [], "redirect_url": "", "webhook_urls": null, "total_discount": 0, "display_total_discount": "MXN 0.00", "shipping": null, "cash_change": 0, "shipping_method": null, "shipping_methods": [], "timezone": "", "scheduled_at": "", "billing_address": { "id": 191, "user_id": "", "first_name": "Pablo", "last_name": "Murillo", "phone": "+551146733466", "identity_document": "", "lat": -22.943934, "lng": -43.182984, "address1": "Jose luis lagrange 3, 12", "address2": "Polanco I Sección", "city": "MIGUEL HIDALGO", "zipcode": "11510", "state_name": "CIUDAD DE MÉXICO", "country_code": "MX", "additional_description": "confirmar", "address_type": "home", "is_default": false, "created_at": "2025-02-26T21:38:07Z", "updated_at": "2025-02-26T21:38:07Z", "email": "[email protected]", "identity_document_type": "", "country": "" }, "payment_link": "", "display_shipping_tax_amount": "MXN 0.00", "display_total_tax_amount": "MXN 1.15", "shipping_tax_amount": 0, "total_tax_amount": 115, "user_id": "", "include_payment_options": [], "redirect_urls": { "success": "", "pending": "", "error": "", "fallback": "", "close": "" }, "created_at": "", "updated_at": "", "payer_info": null, "discount_amount": 100, "shipping_discount_amount": 0, "device_fingerprint": "", "expired_at": "", "version": "0", "fraud": { "analysis": { "score": 0.113950945, "processor": "SIFT", "risk_level": "", "status": "automatic_decision", "type": "", "fraud_decision": "", "details": "", "processor_response": "" } }, "display_total_interest_amount": "", "payment_method": "", "token": "", "statement_descriptor": "", "browser_details": { "screen_height": 1000, "screen_width": 2000, "user_agent": "", "ip_address": "", "color_depth": 0, "java_enabled": false, "java_script_enabled": false, "language": "", "time_zone_offset": 0, "accept_header": "" }, "callback_urls": null }, "custom_fields": [] } -
-
Redirect to PayPal
The purchase API will return a response with a
pendingstatus and anext_actioncontaining the PayPal checkout URL, to which we should redirect the user.{ "order": { "order_id": "620bbbf4-1f08-4cda-8609-dade541cb80e", "store_code": "all", "currency": "MXN", "tax_amount": 0, "display_tax_amount": "", "shipping_amount": 0, "display_shipping_amount": "MXN 0.00", "items_total_amount": 2175, "display_items_total_amount": "MXN 21.75", "sub_total": 2075, "display_sub_total": "MXN 20.75", "total_amount": 2190, "display_total_amount": "MXN 21.90", ... "status": "pending", "payment": { "data": { "method_type": "wallet", "processor": "paypal_wallet", "status": "pending", "external_transaction_id": "6L9248503S6803027", "next_action": { "action": "authorization_wallet", "url": "", "authorization_wallet": { "token": "6L9248503S6803027", "redirect_url": "https://www.sandbox.paypal.com/checkoutnow?token=6L9248503S6803027" } }, ... } }, "created_at": "", "updated_at": "", ... }, "custom_fields": [] } -
Check the order status (Polling).
Once we have directed the user to PayPal, we must check the payment status while they authorize it with their account, polling until the status changes.
We have to Get Order and check the
payment.data.status.The expected statuses are:
pending: The user has not yet authorized the payment on PayPal.processed: The user authorized the payment on PayPal, and the capture was successful.denied: An error occurred while processing the payment.
Response
{ "token": "ce7f91cc-7306-4a36-b9a8-b266545c56ba", "order_type": "DEUNA_CHECKOUT", "order": { "order_id": "620bbbf4-1f08-4cda-8609-dade541cb80e", "store_code": "all", "currency": "MXN", "tax_amount": 0, "display_tax_amount": "MXN 0.00", "shipping_amount": 0, "display_shipping_amount": "MXN 0.00", "items_total_amount": 2175, "display_items_total_amount": "MXN 21.75", "sub_total": 2075, "display_sub_total": "MXN 20.75", "total_amount": 2190, "display_total_amount": "MXN 21.90", "discounts": [], "status": "succeeded", "payment": { "data": { "method_type": "wallet", "processor": "paypal_wallet", "status": "processed", "external_transaction_id": "5S773340XV029382D" } }, "created_at": "2025-02-26 21:38:07.860816361 +0000 UTC", "updated_at": "", "callback_urls": null }, "custom_fields": [], "checkout_modules": [], "refunds": [] }
-
-
With Vaulting
This is the flow to follow when tokenization of a PayPal account is required to complete the purchase.
The response from Get Payment Methods would be as follows:
{ "data": [ { "enabled": true, "method_type": "wallet", "processor_name": "paypal_wallet", // PayPal Wallet identifier "exclude_cvv": false, "stored_payment_methods": [ { "payment_method": "adb1ef51-e073-49f5-ba3b-a7e42344fd15", "account_identifier": "[email protected]" } ], "id": "58745b8e-7127-44ea-84ef-656b3ffc611b", // Payment method ID "authorization": { "required": true, "flow": "consent" } } ] }At this point, the user should be given the option to add a new account or proceed with the purchase using a previously tokenized account.
-
Add a new PayPal account
In order to tokenize a new account, the following steps must be followed:
- Create customer’s consent.
At this step, we will create a PayPal authorization request for the user.- Request
curl --location --request POST '{{base_url}}/merchants/orders/{{order_token}}/consent?payment_method_id={{payment_method_id}}' \ --header 'X-API-KEY: {{merchant_private_key}}' \ --header 'Content-Type: application/json' \ --header 'X-Request-Id: xxxxx' \ --header 'Authorization: Bearer {{user_token}}' - Response
{ "id": "1625a32a-df4c-4d9b-aec1-4510b3625865", "type": "transaction.authentication.pending", "created": "1740608931", "data": { "order": { "order_token": "7e975d44-a061-4d70-af0f-673f6ee56445", "transaction_id": "51b38afd-150f-419a-b718-b583209160fe", "external_transaction_id": "" }, "consent": { "id": "6fe9a045-9a46-4b25-8b60-d5a9586494c5", "status": "pending", "expires_at": "2025-02-26T22:38:51Z", "authorization_id": "5KA20765HT8087515", "redirect_url": "https://www.sandbox.paypal.com/agreements/approve?approval_session_id=5KA20765HT8087515" }, "error": null } }
- Request
- Redirect to PayPal
The API will return the consent aspendingand a PayPal URL where the user must enter their account details and authorize its use.{ "id": "1625a32a-df4c-4d9b-aec1-4510b3625865", "type": "transaction.authentication.pending", "created": "1740608931", "data": { "order": { "order_token": "7e975d44-a061-4d70-af0f-673f6ee56445", "transaction_id": "51b38afd-150f-419a-b718-b583209160fe", "external_transaction_id": "" }, "consent": { "id": "6fe9a045-9a46-4b25-8b60-d5a9586494c5", "status": "pending", "expires_at": "2025-02-26T22:38:51Z", "authorization_id": "5KA20765HT8087515", "redirect_url": "https://www.sandbox.paypal.com/agreements/approve?approval_session_id=5KA20765HT8087515" }, "error": null } } - Get customer’s consent status (Polling)
Once we have directed the user to PayPal, we must check the consent status while they authorize the use of their account, polling until the status changes.- Request
curl --location '{{base_url}}/merchants/orders/{{order_token}}/consent' \ --header 'X-API-KEY: {{merchant_private_key}}' \ --header 'Content-Type: application/json' \ --header 'X-Request-Id: xxxxx' \ --header 'Authorization: {{user_token}}' - Response
The expected statuses are:
{ "id": "4d226ecf-cd9a-4cc0-a3cf-fa8b2d0efab7", "type": "transaction.authentication.updated", "created": "1740609613", "callback_url": "", "data": { "request_id": "62551ffd-6d67-46cb-a436-f1ec3aa56087", "order": { "order_token": "00000000-0000-0000-0000-000000000000", "transaction_id": "", "external_transaction_id": "" }, "consent": { "id": "61fd7eb8-8a42-43fc-89d1-ab5c5ccaa0b9", "status": "success", "expires_at": "0001-01-01T00:00:00Z", "authorization_id": "95778196PH100683G", "redirect_url": "" }, "error": null } } pending: The user has not yet authorized the use of their PayPal account.success: The user authorized the use of their PayPal account, and the account was successfully tokenized.denied: An error occurred while tokenizing the account, or the user did not authorize the use of their account.expired: The user did not authorize the use of their account in time.
Once the user's consent is authorized, the account will appear in the
stored_payment_methodsof the response from Get Payment Methods.
{ "data": [ { "enabled": true, "method_type": "wallet", "processor_name": "paypal_wallet", // PayPal Wallet identifier "exclude_cvv": false, "stored_payment_methods": [ { "payment_method": "6fe9a045-9a46-4b25-8b60-d5a9586494c5", // data.consent.id "account_identifier": "[email protected]" } ], "id": "58745b8e-7127-44ea-84ef-656b3ffc611b", // Payment method ID "authorization": { "required": true, "flow": "consent" } } ] }At this point, we should have a tokenized PayPal account, these token will be required for the next steps. This account token will be the
payment_methodfield from the list ofstored_payment_methodsin the response of Get Payment Methods, or it can also be thedata.consent.idfield from the API response of Create or Get Consent. - Request
- Create customer’s consent.
-
Installments (Optional)
We can check the available installments for the user's PayPal account with the following request:
curl --location '{{base_url}}/merchants/transactions/orders/{{order_token}}/installments?payment_method={{payment_method}}&method_type=wallet&payment_method_id={{payment_method_id}}' \ --header 'x-api-key: {{merchant_public_key}}'Response
{ "installments": [ { "installments": 3, "installments_amount": 3333, "display_installments_amount": "MXN 33.33", "installment_rate": 0, "display_installment_label": "3 de $33.33 sin interés", "plan_option_id": "2e0cc595-40e6-4ecf-b43b-35d5c33f88b6", "installment_total_amount": 10000, "installment_tax": [], "display_installment_total_amount": "MXN 100.00" }, { "installments": 6, "installments_amount": 1666, "display_installments_amount": "MXN 16.66", "installment_rate": 0, "display_installment_label": "6 de $16.66 sin interés", "plan_option_id": "25c7ef41-ebe8-4197-bdb3-f8651c261ea8", "installment_total_amount": 10000, "installment_tax": [], "display_installment_total_amount": "MXN 100.00" } ] } -
Perform the Purchase
To make a Purchase V1, you can refer to the following guide. Here is a list of required fields for PayPal Wallet:
Field Description Value method_typeDEUNA payment method type. walletprocessor_namePayPal Wallet payment method identifier. paypal_walletpayment_methodPayPal account token. 6fe9a045-9a46-4b25-8b60-d5a9586494c5payment_method_idPayPal Wallet payment method ID returned in the idfield of the Get Payment Methods response.58745b8e-7127-44ea-84ef-656b3ffc611b- Payload
{ "token": "{{order-token}}", "method_type": "wallet", // required for PayPal Wallet "processor_name": "paypal_wallet", // required for PayPal Wallet "email": "[email protected]", "payment_method": "{{payment_method}}", // required "payment_method_id": "{{payment_method_id}}", // required "device_id": "xxxxxxx", // PayPal device ID, used in STC "specific_fields": { "callbacks": { "on_success": "https://example.com" // required for PayPal Wallet } } }
To make a Purchase V2, you can refer to the following guide. Here is a list of required fields for PayPal Wallet:
Field Description Value payment_source.method_typeDEUNA payment method type walletpayment_source.processorPayPal Wallet payment method identifier. paypal_walletpayment_source.payment_methodPayPal account token. 6fe9a045-9a46-4b25-8b60-d5a9586494c5payment_source.payment_method_idPayPal Wallet payment method ID returned in the idfield of the Get Payment Methods response.58745b8e-7127-44ea-84ef-656b3ffc611b- Payload
{ "order_type": "DEUNA_CHECKOUT", "order_token": "{{order-token}}", "payer_info": { "email": "[email protected]" }, "payment_source": { "method_type": "wallet", // required for PayPal Wallet "processor": "paypal_wallet", // required for PayPal Wallet "payment_method": "{{payment_method}}", // required "payment_method_id": "{{payment_method_id}}" // required }, "anti_fraud_info": { "device": { "id": "xxxxxxx" // PayPal device ID, used in STC } } }
Response
{ "order_type": "DEUNA_CHECKOUT", "order_token": "c582917a-07d2-4f07-b107-fd535e5565cb", "order": { "order_id": "777e66e5-3326-4b04-ad0a-93be7f2028bb", "store_code": "all", "currency": "MXN", "tax_amount": 0, "display_tax_amount": "", "shipping_amount": 0, "display_shipping_amount": "MXN 0.00", "items_total_amount": 2175, "display_items_total_amount": "MXN 21.75", "sub_total": 2075, "display_sub_total": "MXN 20.75", "total_amount": 2190, "display_total_amount": "MXN 21.90", ... "status": "succeeded", "payment": { "data": { "method_type": "wallet", "processor": "paypal_wallet", "customer": { "email": "[email protected]", "id": "9d920735-c3b1-4908-aba2-762d86fda7e0", "first_name": "", "last_name": "" }, "status": "processed", "external_transaction_id": "0YF74805EM9345944", ... } }, ... "callback_urls": null } }Expected Statuses:
succeeded: Payment completed successfully.denied: An error occurred while processing the payment.
- Payload
-
Integrate FraudNet
Fraudnet is a library developed by PayPal that analyzes the data sent through the browser during the entire purchase process to prevent possible fraud in the transactions made.
Fraudnet must be running throughout the transaction process. For its integration, PayPal provides the following documentation: Integrate FraudNet
Updated 7 days ago