Run a merchant-initiated recurring transaction

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:

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

   Example Braintree PayPal Sale Response

   {
     "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:
   

   Example Merchant-Initiated 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:
   
   Example 200 Response

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