Run a merchant-initiated recurring transaction

Background
Before starting this tutorial, make sure you understand the following topics from the Quick start section:

You may want to support merchant-initiated transactions for your customers, such as for recurring transactions. This might be for an auto-ship program or payment flow.

πŸ‘

Supported APMs

In order to run recurring transactions through a supported alternative payment method (APM), you must use the Individual Iframe (Button URLs) integration method.

To allow for and run merchant-initiated transactions, follow these steps:

  1. Configure Your Account

    Configure your Nexio account to use a supported APM. If you need to have this done, contact Integration Support.

  2. Create Necessary Payment Flow Pages

    Complete step 2 in Button Iframe URLs to create any needed pages.

  3. Configure Pages

    Complete step 3 in Button Iframe URLs to create a Shopping Cart page. Include the URL from the "braintreePayPal" or "adyenSepa" paymentMethod to add that payment option to the checkout page.

    🚧

    Important

    Make sure to include the processingOptions.saveRecurringToken parameter in the body of your one-time-use token request and set it equal to true.

    Complete step 4 in Button Iframe URLs to create a Confirm/Place Order page.

    Complete step 5 in Button Iframe URLs to create a Checkout page. Include the URL from the "braintreePayPal" or "adyenSepa" paymentMethod to add that payment option to the checkout page.

  4. Shopper Completes Payment and You Save APM Token

    If the customer clicks the PayPal (through Braintree) button as the payment method (steps 6-7 in Button Iframe URLs) or completes the values in the SEPA form and clicks the Pay button, then, in the event posted to your window, the response includes an apm.token parameter.

    Save the apm.token value somewhere in order to use it again (probably similar to how you save TokenEx tokens already).

    ❗️

    Warning

    This apm.token value cannot be retrieved through the API at any other time.

    By way of example, a response may look like the following. Notice the apm object and its token:

    {
      "id": "eyJuYW1lIjoiYnJhaW50cmVlUGF5UGFsIiwibWVyY2hhbnRJZCI6IjEwMTAzOSIsInJlZk51bWJlciI6InA0NXljeWQ5IiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9",
      "merchantId": "101039",
      "transactionDate": "2021-07-13T22:12:56.780Z",
      "transactionStatus": "settled",
      "amount": 4,
      "transactionType": "sale",
      "currency": "USD",
      "gatewayResponse": {
        "result": "settling",
        "refNumber": "p45ycyd9",
        "gatewayName": "braintreePayPal",
        "message": "settling"
      },
      "data": {
        "amount": 4,
        "currency": "USD",
        "settlementCurrency": "USD",
        "customer": {
          "lastName": "Test",
          "shipToAddressOne": "123 Ship St",
          "shipToPhone": "5033335678",
          "orderNumber": "1151057c04214a688c382ee1f666e76e",
          "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"
        }
      },
      "apm": {
        "token": "apm:66b742ee-7abc-4e36-81ea-0a26d23d2822"
      }
    }
    

  5. Run Merchant-Initiated Payment

    Later, when you are ready to initiate another transaction for the customer without their input, use that stored apm.token value from step 4 above to run a payment.

    Send a POST request to the APM Run Transaction endpoint, as in the following example. Notice the inclusion of the apm object with its token in the body of the request:

    curl -X POST https://api.nexiopaysandbox.com/apm/v3/process \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: Basic [Base64_encoded_login]'
      -d '{
      "isAuthOnly": false,
      "apm": {
        "token": "apm:66b742ee-7abc-4e36-81ea-0a26d23d2822"
      },
      "data": {
        "currency":"USD",
        "amount": 9.95,
        "description": "test purchase",
        "customer": {
          "orderNumber": "sdgsrgrsb",
          "firstName":"Joe",
          "lastName":"Brown",
          "billToAddressOne": "123 Street",
          "billToAddressTwo": "Box 232",
          "billToCity": "Narnia",
          "billToState": "TX",
          "billToPostal": "46632",
          "billToCountry": "USA"
        }
      }
    }'
    

    You will then get a response, which will be similar to other payment responses that you normally get. On success, the response looks similar to the following:
    {
      "id": "eyJuYW1lIjoiYnJhaW50cmVlUGF5UGFsIiwibWVyY2hhbnRJZCI6IjEwMTAzOSIsInJlZk51bWJlciI6Ims3ZDN6cDJlIiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9",
      "merchantId": "101039",
      "transactionDate": "2021-07-13T22:14:03.514Z",
      "transactionStatus": "settled",
      "amount": 9.95,
      "transactionType": "sale",
      "currency": "USD",
      "gatewayResponse": {
        "result": "settling",
        "refNumber": "k7d3zp2e",
        "gatewayName": "braintreePayPal",
        "message": "settling"
      },
      "data": {
        "amount": 88,
        "currency": "USD",
        "settlementCurrency": "USD",
        "customer": {
          "orderNumber": "sdgsrgrsb",
          "firstName": "Joe",
          "lastName": "Brown",
          "billToAddressOne": "123 Street",
          "billToAddressTwo": "Box 232",
          "billToCity": "Narnia",
          "billToState": "TX",
          "billToPostal": "46632",
          "billToCountry": "USA"
        }
      }
    }