Run a merchant-initiated recurring transaction

Background
Before starting this tutorial, make sure you understand the following topics from the Quick start section: Sandbox environments (especially about testing). Authentication (about authenticating using your API user and when you need a login versus a one-time-use token).

Background

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

Sandbox environments (especially about testing).
Authentication (about authenticating using your API user and when you need a login versus a one-time-use token).

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

PayPal (with Braintree)

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

For additional information about recurring transactions, see Recurring billing overview.

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

Configure Your Account

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

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

Complete step 3 in Button Iframe URLs to create a Shopping Cart page. Include the URL from the "braintreePayPal" 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.

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), 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"
  }
}

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"
    }
  }
}