For merchant accounts that are integrated with a payout provider, the checkout process can include the recipient's payout account as a payment method. This is referred to as a spendback.

🚧

Prerequisites:

• Merchant account configured for payouts.
• Payout provider that supports spendback.

A spendback submitted through Nexio may not receive a synchronous reply that includes an actionable state. Receiving pending in your synchronous response is possible, so, to get asynchronous changes and updates, it is necessary to either set up one or more webhooks or send a GET request to the View a spendback or View spendbacks endpoint.

📘

Note

Spendback refunds are not currently supported through Nexio.

Adding a spendback as a payment option

To add spendbacks to your checkout page, follow the steps below.

1. If necessary, contact Integrations Support to ensure your account is configured correctly and to determine whether your payout provider supports spendbacks.

2. Create a checkout page that gives the customer the opportunity to submit address and payment information, and for the page to calculate and display tax and shipping cost, as applicable.

3. Add a link, button, image, or other element for the spendback payment option.

4. When the customer chooses the spendback payment option and attempts to complete the transaction, send a POST request to the Submit spendback endpoint.

   Include the following required parameters:

   • amount
   • currency
   • One of the following:
     • recipientId
     • recipientRef
     • email
   Example Request

   curl -X POST https://api.nexiopaysandbox.com/payout/v3/spendback \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H 'Authorization: Basic [Base64_encoded_login]'
     -d '{
       "amount": 14.83,
       "currency": "USD",
       "recipientId": 137241
   }'
   

   
   A successful response returns with the following JSON:
   Example 200 Response

   {
     "id": 2598,
     "spendbackRef": "43b57dce-4dca-474a-84f4-4684f3a8aa52",
     "recipientId": 137241,
     "recipientRef": "9467e04a-3f19-473f-a8b3-a1bc09a2ede8",
     "payoutAccountId": 3927,
     "providerId": "12610",
     "providerType": 10,
     "providerSpendbackRef": "spnd_bk_519cbf18-b472-11ec-a6cf-06ff2a295e6f",
     "amount": 14.83,
     "currency": "USD",
     "spendbackDate": "2022-02-26T13:35:00Z",
     "spendbackStatus": 20,
     "createdAt": "2022-02-26T13:35:00Z",
     "updatedAt": "2022-02-27T05:39:59.000Z"
   }
   

   
   

5. Redirect the customer to the next appropriate page.

   • If the payment was successful (spendbackStatus of 20), the API response JSON includes the status, payment ID and order number. Redirect the customer to a success page.

   • If the payment status is pending (spendbackStatus of 10), the API response JSON includes the status, payment ID and order number. Determine how you want to treat this status. You may need a pending state or consider it a failed transaction.

   • If the payment failed (spendbackStatus of 90), check the providerResponse parameter for details. For additional help, see Handling errors and declines. Redirect the customer to a failure page.

   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. Example event message response for webhook:

   Example Spendback Response

   {
     "eventType": "SPENDBACK",
     "spendbackStatus": 20,
     "spendbackId": 2598,
     "spendbackRef": "43b57dce-4dca-474a-84f4-4684f3a8aa52"
   }