Custom Redirect (Redirect URLs)

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

To integrate with a single APM using a custom redirect, follow the steps below.

  1. Configure Your Account

    Contact Integrations Support to enable the desired APM on your merchant account.

  2. 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.

  3. 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.

    Example
    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": "[email protected]",
          "orderNumber": "210058A"
        }
      },
      "customerRedirectUrl": "https://[your-ecommerce-website]"
    }'
    


    A successful request will return an array of redirectUrls. This array is a list of all APMs currently enabled on your merchant account. Copy the url of the desired APM for use in step 4.

    Example 200 Response
    {
      "expiration": "2018-09-18T15:43:05.664Z",
      "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
      "expressIFrameUrl": "https://www.api.nexiopaysandbox.com/v3?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2",
      "redirectUrls": [
        {
          "paymentMethod": "nihaoPayAliPay",
          "url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=nihaoPayAliPay"
        },
        {
          "paymentMethod": "payPal",
          "url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=payPal"
        },
        {
          "paymentMethod": "paynet",
          "url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=paynet"
        },
        {
          "paymentMethod": "openpaySpei",
          "url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=openpaySpei"
        },
        {
          "paymentMethod": "nihaoPayUnionPay",
          "url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=nihaoPayUnionPay"
        },
        {
          "paymentMethod": "nihaoPayWechatPay",
          "url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=nihaoPayWechatPay"
        }
      ],
      "buttonIFrameUrls": [...]
    }
    
  4. 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.

  5. Shopper Completes Payment

    This step varies slightly depending on the APM.

    • Voucher payments (Paynet and SPEI): 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.

  6. 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.

    Successful Payment Redirect
    https://your-ecommerce-website.example.com?status=pending&paymentId=eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0&orderNumber=228c3778fe
    
    Failed Payment Redirect
    https://your-ecommerce-website.example.com?status=pending&error=error_message
    

    Example response for a webhook:

    Example Sale Response
    {
      "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": "[email protected]",
          "shipToState": "OR"
        }
      }
    }
    

Did this page help you?