Custom Redirect (Redirect URLs)
Background |
---|
Before starting this tutorial, make sure you understand the following topics from the Quick start section:
|
The single APM integration option allows you to send shoppers directly to a single APM to complete payment.
Upon completion (payment success or failure) shoppers will be redirected to the customer redirect URL provided in step 3 of the tutorial below.
Supported APMs
Note
- Apple Pay, Google Pay, Klarna, PayPal (with Braintree), and Sofort through Checkout.com are not currently supported through Redirect URLs.
To integrate with a single APM using a custom redirect, follow the steps below.
-
Configure Your Account
Contact Integrations Support to enable the desired APM on your merchant account.
-
Create a Checkout Page
On the page, for each APM you want, include a button, image, link, or similar element that the consumer can click. For more information, see the steps in Creating a card checkout page with your own form.
-
Request an APM Redirect URL
Send a
POST
request to the Create APM one-time-use token endpoint.
Include the following required parameters:data.amount
data.currency
data.customer.firstName
data.customer.lastName
data.customer.email
data.customer.orderNumber
customerRedirectUrl
If the APM supports it, you can also include Pay Later messaging.
curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Basic [Base64_encoded_login]' -d '{ "data": { "amount": 29.99, "currency": "USD", "customer": { "firstName": "Maria", "lastName": "Velasquez", "email": "mvelaquez@example.com", "orderNumber": "210058A" } }, "customerRedirectUrl": "https://[your-ecommerce-website]" }'
A successful request will return an array ofredirectUrls
. This array is a list of all APMs currently enabled on your merchant account. Copy theurl
of the desired APM for use in step 4.{ "expiration": "2018-09-18T15:43:05.664Z", "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2", "asyncTraceId": "830d36f6-a5e3-4455-9600-3a55b63e2fc2", "expressIFrameUrl": "https://www.api.nexiopaysandbox.com/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2", "redirectUrls": [ { "paymentMethod": "payPal", "url": "https://www.api.nexiopaysandbox.com/v3/popup?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=payPal" }, { "paymentMethod": "paynet", "url": "https://www.api.nexiopaysandbox.com/v3/popup?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=paynet" } ], "buttonIFrameUrls": [ ] } -
Redirect the Shopper to the APM
For each APM, add the
url
copied from step 3 to the appropriate form action, onClick location.url event, link src, and so forth for the element you added in step 2.Now, when the page loads, the shopper will see a button, image, and so forth for the APM (or APMs). The shopper clicks the element and then gets redirected (or a popup window opens) to the APM to complete payment.
-
Shopper Completes Payment
This step varies slightly depending on the APM.
- Voucher payments (Paynet): Users will be prompted to print or close the voucher page
- All other APMs: Users will be prompted to complete the transaction
Afterward, the popup window will close and they will be redirected back to the merchant website specified in the
customerRedirectUrl
from Step 3. Nexio provides a response via query string parameters in the URL.If your merchant account is configured to receive webhooks, in addition to the above, Nexio provides responses to the webhook URLs that have been registered.
-
Shopper Redirected
Once the shopper has completed payment (or payment has failed) they will be redirected to the
customerRedirectUrl
you provided in step 3.- If the payment was successful, the redirect URL will include the status, payment ID and order number as query parameters.
- If the payment failed, the redirect URL will include the status and an error message as query parameters.
If your merchant account is configured to receive webhooks, in addition to the above, Nexio provides responses as event messages to the webhook URLs that have been registered.
https://your-ecommerce-website.example.com?status=pending&paymentId=eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0&orderNumber=228c3778fehttps://your-ecommerce-website.example.com?status=pending&error=error_message
Example response for a webhook:
{ "id": "eyJuYW1lIjoicGF5UGFsIiwibWVyY2hhbnRJZCI6IjEwMDAzOSIsInJlZk51bWJlciI6IjlLQTI2NzUwSEs5NzM2OTNBIiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9", "merchantId": "100039", "transactionDate": "2020-06-29T18:54:01.087Z", "transactionStatus": "settled", "amount": 1.15, "transactionType": "sale", "currency": "USD", "gatewayResponse": { "result": 201, "refNumber": "9KA26750HK973693A", "gatewayName": "payPal", "message": 201 }, "data": { "amount": 1.15, "currency": "USD", "settlementCurrency": "USD", "customer": { "lastName": "Test", "shipToAddressOne": "123 Ship St", "shipToPhone": "5033335678", "orderNumber": "054204daf0f7456bac59a014e952fb33", "shipToCountry": "US", "shipToAddressTwo": "Warehouse 456", "billToState": "UT", "billToCity": "Testerville", "shipToPostal": "67890", "firstName": "Nexio", "shipToCity": "Shipperville", "billToAddressOne": "123 Test St", "billToCountry": "US", "billToPostal": "12345", "billToAddressTwo": "Suite 123", "billToPhone": "8015551234", "email": "nexiotest@example.com", "shipToState": "OR" } } }
Updated 7 months ago