> For the complete documentation index, see [llms.txt](https://docs.2checkout.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.2checkout.com/get-started-with-the-2checkout-api/get-started-with-the-2checkout-api/authentication-and-use-cases/2checkout-api-use-cases/payment-flow-for-ewallets-online-payment-methods.md). # Payment flow for eWallets (online payment methods) E-wallets are online payment methods where the order is registered by 2Checkout, but the shopper has to reach a 3rd party's website in order to authenticate and finalize the payment. PayPal is one of the most used E-wallet solutions that dominate the eCommerce world, but other local players, especially in Asian countries, are starting to gain market share. The following payment methods are supported for the E-wallet (online payment methods) flow PayPal, Alipay, WeChat, iDeal. ## Availability Available to all 2Checkout accounts. ## PayPal ### Payment method object structure
ParameterType / Description
ReturnURL

Required (string)

The return URL is the page on your website to which PayPal redirects your buyer's browser after the buyer logs in to PayPal and approves the payment. Typically, this is a secure page ( https://...) on your site.

Email

Optional (string)

Email address customers use for their PayPal account.

### Request sample ```json { "Language":"en", "Country":"US", "CustomerIP":"10.10.10.10", "Source":"Website", "ExternalCustomerReference":"externalCustomerId", "Currency":"USD", "MachineId":"123456789", "Items":[ { "Code":"DD996A4DB3", "Quantity":1 } ], "BillingDetails":{ "FirstName":"Customer First Name", "LastName":"Customer Last Name", "CountryCode":"US", "State":"New York", "City":"New York", "Address1":"Example Street", "Zip":"10005", "Email":"customer@email.com" }, "PaymentDetails":{ "Type":"PAYPAL", "Currency":"USD", "PaymentMethod":{ "RecurringEnabled":false, "ReturnURL":"http:\/\/mywebsite.com\/order\/", "Email":"customer@email.com" } } } ``` ### Redirecting shoppers to PayPal If the order is placed successfully, the 2Checkout API responds with the complete order information. Inside the `PaymentDetails` node, you will find the `PaymentMethod` node that contains the `RedirectURL`. The shopper needs to be redirected to this URL that takes them to the PayPal website to finalize the payment. Once the payment is finalized, shoppers are redirected back to the `ReturnURL`. ### PayPal Express - Alternative Flow In some checkout flows, the user experience might require some details filled in by the shopper on PayPal's side. In order to streamline the checkout experience, this information can be used when placing orders by using the PayPal Express payment method. These are the required steps for the PayPal Express flow: 1. First, you must retrieve the `RedirectURL` from PayPal by calling the **getPayPalExpressCheckoutRedirectURL** method for JSON-RPC and SOAP, or by making a PUT request to /paymentmethods/PAYPAL\_EXPRESS/redirecturl/ on REST. 2. The body of the request must contain the order object with, at a minimum, the product information as well as the payment details: the customer's email address and a `ReturnURL`, the page on the shop's side where the shopper is redirected after the flow is completed on the PayPal's side. 3. The `ReturnURL` parses the response that PayPal sends in order to fetch the needed information and finalize the payment. 4. The **getPayPalExpressCheckoutRedirectURL** method will return a URL where the shopper needs to be redirected in order to complete the payment. 5. Once the shopper completes the payment, PayPal returns the shopper to the URL provided in the ReturnURL. The information provided by the shopper on PayPal's side is available in the GET parameters of the `ReturnURL` (all information is MIME base64 encoded): * billing details (under the `billingDetails` key) * delivery details (under the `deliveryDetails` key) * a token in the URL. 6. If the shopper cancels their payment, then the cancel key will be returned in the URL. 7. The information provided in the billing and delivery details must be filled in the order object. The payment method object will look like this:
ParameterType / Description
Email

Required (string)

The email of the customer, as used when triggering the getPayPalExpressCheckoutRedirectURL method.

Token

Required (string)

The token returned by PayPal.

ReturnURL

Required (string)

The return URL on the shop side that will handle successful orders.

CancelURL

Required (string)

The return URL on the shop side that will handle canceled orders.

In JSON, this looks like: ```json "PaymentDetails": { "Type": "PAYPAL_EXPRESS", "Currency": "EUR", "CustomerIP": "91.220.121.21", "PaymentMethod": { "Email": "customer@email.com", "Token": "EC-470284976K7901234", "ReturnURL": "http://shop.com/place_order_api_json_paypal_express_response.php", "CancelURL": "http://shop.com/place_order_api_json_paypal_express_response.php?cancel=true" } } ``` ## Alipay ### Payment method object structure Alipay does not require any mandatory fields to be sent in the `PaymentDetails` node of the request. ### Request sample ```json { "Language":"en", "Country":"HK", "CustomerIP":"10.10.10.10", "Source":"Website", "ExternalCustomerReference":"externalCustomerId", "Currency":"CNY", "MachineId":"123456789", "Items":[ { "Code":"DD996A4DB3", "Quantity":1 } ], "BillingDetails":{ "FirstName":"Customer First Name", "LastName":"Customer Last Name", "CountryCode":"HK", "State":"Hong Kong", "City":"Hong Kong", "Address1":"Example Street", "Zip":"999077", "Email":"example@email.com" }, "PaymentDetails":{ "Type":"ALIPAY", "Currency":"CNY", "PaymentMethod":{ "RecurringEnabled":false } } } ``` ### Redirecting shoppers to Alipay If the order is placed successfully, the 2Checkout API responds with the complete order information. Inside the `PaymentDetails` node, you will find the `PaymentMethod` / `Redirect` node that contains the URL. The shopper needs to be redirected to this URL. This takes them to the Alipay website, where they can finalize the payment. ## WeChat ### Payment method object structure
ParameterType / Description
ReturnURL

Required (string)

The URL address to which customers are redirected after the payment is completed successfully.

CancelURL

Required (string)

The URL address to which customers are redirected after the payment is completed unsuccessfully.

### Request sample ```json { "Language":"en", "Country":"CN", "CustomerIP":"10.10.10.10", "Source":"Website", "ExternalCustomerReference":"externalCustomerId", "Currency":"USD", "MachineId":"123456789", "Items":[ { "Code":"DD996A4DB3", "Quantity":1 } ], "BillingDetails":{ "FirstName":"Customer First Name", "LastName":"Customer Last Name", "CountryCode":"CN", "State":"Beijing", "City":"Beijing", "Address1":"Example Street", "Zip":"102629", "Email":"example@email.com" }, "PaymentDetails":{ "Type":"WE_CHAT_PAY", "Currency":"USD", "PaymentMethod":{ "RecurringEnabled":false, "ReturnURL":"http:\/\/yourreturnurl.com", "CancelURL":"http:\/\/yourcancelurl.com" } } } ``` ### Redirecting shoppers to WeChat If the order is placed successfully, the 2Checkout API responds with the complete order information. Inside the `PaymentDetails` node, you will find the `PaymentMethod` / `Authorize` node that contains the Href, Method, and Params node. The shopper needs to be redirected to this Href, using the Method mentioned in the API response. Additionally, the parameters in the Params node need to be sent as key-value pairs in the request. This takes shoppers to the WeChat website, where they can finalize the payment. ## iDeal iDeal is a standardized online banking-based payment method tailored to users in the Netherlands. iDEAL supports online payments via secure online transfers directly between bank accounts. To place an order with iDeal, the shopper needs to select the bank that they use. The full list of supported banks can be queried via API by calling the **getIdealIssuerBanks** method (SOAP and JSON-RPC) or making a GET request /paymentmethods​/IDEAL​/issuerbanks​/ on REST. The output of this API call is the list of supported banks, as code (to be used when placing the order), and the user-readable name of the bank. ```json [ { "Code":"ABNANL2A+ABN", "Name":"ABN AMRO" }, { "Code":"RABONL2U+RAB", "Name":"Rabobank" }, { "Code":"INGBNL2A+ING", "Name":"ING" } ] ``` ### Payment method Object structure
ParameterType / Description
BankCode

Required (string)

The bank code as returned by the getIdealIssuerBanks API call.

ReturnURL

Required (string)

The URL address to which customers are redirected after the payment is completed successfully.

CancelURL

Required (string)

The URL address to which customers are redirected after the payment is completed unsuccessfully.

BankCode

Required (string)

The bank code as returned by the getIdealIssuerBanks API call.

### Request sample ```json { "Language":"en", "Country":"NL", "CustomerIP":"10.10.10.10", "Source":"Website", "ExternalCustomerReference":"externalCustomerId", "Currency":"EUR", "MachineId":"123456789", "Items":[ { "Code":"DD996A4DB3", "Quantity":1 } ], "BillingDetails":{ "FirstName":"Customer First Name", "LastName":"Customer Last Name", "CountryCode":"NL", "State":"North Holand", "City":"Amsterdam", "Address1":"Example Street", "Zip":"1183", "Email":"example@email.com" }, "PaymentDetails":{ "Type":"IDEAL", "Currency":"EUR", "PaymentMethod":{ "ReturnURL":"http:\/\/yourreturnurl.com", "CancelURL":"http:\/\/yourcancelurl.com", "BankCode":"RABONL2U+RAB" } } } ``` ### Redirecting shoppers to finalize the payment Once the order has successfully been placed, in the response in the `PaymentDetails` / `PaymentMethod` / `Authorize` node, you have the information needed to compose the URL where the shopper needs to finalize the payment. The shopper needs to reach the Href via the Method HTTP method, with the key-values in the Params in the request parameters. ```json "PaymentDetails":{ "Type":"IDEAL", "Currency":"eur", "PaymentMethod":{ "Authorize":{ "Href":"https:\/\/api.avangate.com\/6.0\/scripts\/ideal\/authorize", "Method":"GET", "Params":{ "avng8apitoken":"ukaiuljobm84jmt3" }, "AvangateId":null }, "ReturnURL":"http:\/\/yourreturnurl.com", "CancelURL":"http:\/\/yourcancelurl.com", "BankCode":"RABONL2U+RAB", "RecurringEnabled":false }, "CustomerIP":"5.12.32.22" }, ``` Once the shopper has finalized the payment, the order will be marked with 'status = Complete'. ## Integration test cases 1. Build a request in order to place a new order, with all the relevant information. Make sure that when the order is sent in the API, the response contains an order object (order was placed successfully). 2. Make sure that you handle the redirect to the 3rd party site. 3. If you have any additional webhook integrations, make sure that the webhooks are correctly configured and that the notifications are received and processed successfully. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.2checkout.com/get-started-with-the-2checkout-api/get-started-with-the-2checkout-api/authentication-and-use-cases/2checkout-api-use-cases/payment-flow-for-ewallets-online-payment-methods.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.