How to add IFX integration as a payment provider

Using our IFX platform, Arc Subscriptions is providing you more options when it comes to payment processing. Now you can use any payment gateways of your choice using our extensible payment gateways capabilities.

Arc Subscription services have several APIs that allow clients to implement their own integrations with payment gateways. This uses the Arc XP IFX Integration which is hosted in AWS environments.

Clients will need to implement the main payment sub-components of its payment gateway IFX integration and connect to Arc Subscriptions using IFX. To create the checkout flows with Arc Subscriptions use the User Guide Here. These will be referred to as part of the descriptions of the IFX integrations that you will complete. Common to all integrations is that they expect limited PII/PCI data to flow back and forth, and that clients are responsible for the safe storage of such data.

Set up IFX integration

Follow through on the IFX documentations to create a new integraion and subscribe to events. This document will not address how to set up and manage IFX integration. Please refer to IFX documentations on them.

• Creating and managing integrations with IFX
• Creating Handlers to Receive Events with IFX
• Subscribe to relevant events
• IFX Event Menu

No matter which payment provider you use, you must follow Steps 1 to 5 (Authenticate, Retrieve products and prices, Add item(s) to the cart, Create an order, and Access payment options) outlined in Checkout to purchase a subscription to create a full purchase flow. See How to add Stripe Intents as a payment provider for implementation details.

You can verify that IFX payment option is enabled by calling getPaymentOptions sdk and verifying paymentMethodType 19 exist in the response. See step 5 on Checkout to purchase a subscription for more details. For each payment options returned, you will see a paymentMethodID, this value, together with the order number are required when calling Sales.initializePayment().

Step 1: Initialize Payment

To start the checkout process for a customer, you will need to initialize a payment session with your gateway. This can be done by calling InitializePayment (GET /sales/public/v1/checkout/order/{orderNumber}/payment/{mid}). This will trigger Arc Sales to call your IFX integration which can then interact with your payment gateway’s APIs.

When a customer calls Arc’s initialize-payment API, Arc will call your IFX initialize-payment integration passing the following parameters collected from the customer. This contains information collected about the customer and the transaction through your IFX integration.

Note

You will have to subscribe to commerce:initialize_payment event using IFX API. After subscribing to the event, you will have to write a synchronous event handler for commerce:initialize_payment event that will take in the information passed by the Arc Subscriptions, communicate with the client’s payment provider, and response back to Arc Subscription in the requested format.

Arc will provide these information to the handler.

{
  "correlationId": "4d8c1b3c-b279-4ef5-bf40-db309c2cddac",
  "gatewayId": 1234,
  "orderNumber": "1234ABCD5678EFGH",
  "amount": 12.34,
  "tax": 5.67,
  "firstName": "Joe",
  "lastName": "Customer",
  "currency": "USD",
  "email": "joe.customer@email.com"
}

Note

The correlationId is a tag that Arc places on all log entries related to this transaction. This can be used as a tag to enable easier troubleshooting.

After receiving the response from Arc, your integration is expected to respond, through IFX, in the following format.

 {
  "orderNumber": "1234ABCD5678EFGH",
  "parameter1": "aaaaaaa",
  "parameter2": "bbbbbbb",
  "parameter3": "ccccccc",
  "parameter4": "ddddddd"
}

These parameters that you send to Arc will be passed to your front end payment form in response to your checkout page calling Arc’s initialize-payment API. The parameters are intended for use by the form to initialize the front-end portion of the flow.

Step 2: Finalize Payment

Once the payment process has been started with your gateway, and the payment information is entered in the hosted form, your checkout page needs to finalize the payment. To do this you will call Arc XP’s Finalize-Payment API. For this part, you will have to subscribe to commerce:finalize_payment event and write an appropriate synchronous handler that returns response requested by the Arc Subscriptions. If you have enabled reCAPTCHA for checkout, you will need to pass the token during Finalize-Payment API call.

In response to that call, Arc will call your Finalize Payment IFX integration passing the following information.

Arc will return the following response. This contains the finalized payment information collected about the customer and the transaction through your IFX integration.

{
  "correlationId": "4d8c1b3c-b279-4ef5-bf40-db309c2cddac",
  "amount": 12.34,
  "currency": "USD",
  "token": "YOUR_PAYMENT_TOKEN",
  "orderNumber": "1234ABCD5678EFGH",
  "cardHolderFirstName": "Joe",
  "cardHolderLastName": "Customer"
}

The token represents the tokenized data in your system, and you must use this data for completing the checkout payment in your integration. Upon receipt of a positive response from your integration, Arc will fulfill the order. If the order is for a subscription, then the token will be retained for future renewal payments.

A positive response must have the following format:

{
  "amount": 12.34,
  "cardholderName": "Joe Customer",
  "expirationMonthYear": "0625",
  "transactionReferenceCode": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
  "creditCardFirstSix": "424242",
  "creditCardLastFour": "1111"
}

If the payment was declined, the response must have the following format:

{
  "error": {
    "message": "do not honor"
  }
}

Your error message will be included in the response from Arc’s finalize-payment API, so you can display it to your customer on your checkout page.

Refund Payment

When a refund against a prior transaction is needed, you can use the IFX integration refundPayment. Again, you will have to subscribe to commerce:refund event and write a handler for the event. From Arc you will receive a request document with the following format:

{
  "originalPaymentToken": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
  "currency": "USD",
  "amount": 2.34,
  "correlationId": "4d8c1b3c-b279-4ef5-bf40-db309c2cddac"
}

If the refund is successful, then please return a response in the following format.

{
  "refundToken":"your refund transaction ID"
}

If the refund fails, you should return a response in the following format.

{
  "error": {
    "message": "do not honor"
  }
}

Update Payment Method

Initialize payment method update

To start the process of updating a subscribers payment method for a reoccurring subscription you can use the IFX Integration IntializePaymentMethodUpdate. Please subscribe to commerce:initialize_update_payment event and write a handler. You will receive the following request document from Arc:

{
  "parameter1": "parameter1",
  "parameter2": "parameter2",
  "parameter3": "parameter3",
  "parameter4": "parameter4",
  "correlationId": "hdsflkjghsdflkgs"
}

You are expected to respond with:

{
  "parameter1": "parameter1",
  "parameter2": "parameter2",
  "parameter3": "parameter3",
  "parameter4": "parameter4"
}

Where the values are passed to your hosted input form by Arc’s initialize-update-payment API.

Finalize payment method update

To complete an update of a subscribers payment method, you should call the finalizeUpdatePayment API. Subscribe to commerce:finalize_payment_update and you will receive from Arc:

{
  "token":"NEW_PAYMENT_TOKEN"
}

Upon receipt of a positive response, Arc will retain the payment token for future subscription renewals. A positive response from you looks as follows:

{
  "redirectUrl": "http://www.redirecturl.com",
  "cardholderName": "Joe Customer",
  "creditCardFirstSix": "343434",
  "creditCardLastFour": "4343",
  "expirationMonthYear": "0926",
  "token": "NEW_PAYMENT_TOKEN"
}

Holding payment method when no charge

Arc will call your Authorize Payment integration to place a hold on your customer’s credit card without charging the card immediately. You should subscribe to commerce:authorize_payment event and write a handler to utilize this functionality. This integration is a companion to the Initialize Payment API and will contain the following request:

{
  "authAmount": 12.34,
  "amount": 12.34,
  "currency": "USD",
  "token": "TOKEN_FROM_FRONT_END",
  "orderNumber": "AAAABBBBCCCCDDDD",
  "cardHolderFirstName": "Joe",
  "cardHolderLastName": "Customer",
  "correlationId": "4d8c1b3c-b279-4ef5-bf40-db309c2cddac"
}

When successful you need to respond with the following.

{
  "orderNumber": "AAAABBBBCCCCDDDD",
  "cardHolderName": "Joe Customer",
  "expirationMonthYear": "0927",
  "creditCardFirstSix": "411111",
  "creditCardLastFour": "1111",
  "transactionReferenceCode": "gfsdkjhkdjg"
}

For a decline, the response must have the following format:

{
  "error": {
    "message":"do not honor"
  }
}

Capture Payment

Your integration will receive this call from Arc to capture a previously authorized payment. You should subscribe to commerce:capture event and write a handler to utilize this functionality. The request looks as follows:

{
  "amount": "12.34",
  "token": "jfdhglksjdfhlgksdf",
  "submitForSettlement": true,
  "correlationId": "4d8c1b3c-b279-4ef5-bf40-db309c2cddac",
  "orderNumber": "AAAABBBBCCCCDDDD"
}

Arc XP expects either a negative (see above) or positive response from you. The positive response must have the following format:

{
  "orderNumber": "AAAABBBBCCCCDDDD",
  "amount": 12.34,
  "transactionReferenceCode": "kdsfghkjfdshlk",
  "cardholderName": "Joe Customer",
  "creditCardFirstSix": "411111",
  "creditCardLastFour": "1111",
  "token": "dsfglkjsdhkg",
  "expirationMonthYear": "0529"
}

Correction Methods

We provide two APIs to enable you to fix or repair payment data stored with Arc XP when something goes wrong between the payment gateway and Arc calls.

Void Authorization

Arc can void a transaction if it was incorrectly stored as successful. You should subscribe to commerce:void_authorize event and write a handler to utilize this functionality. The voidAuthorization IFX integration can be used to void a previously authorized transaction. From Arc you will receive the following document

{
  "token":"shglkfdsjhgldf",
  "orderNumber":"AAAABBBBCCCCDDDD"
}

You are expected to respond with either a negative response (see above) or a positive response in the following format:

{
  "orderNumber": "AAAABBBBCCCCDDDD",
  "cardHolderName": "Joe Customer",
  "creditCardFirstSix": "411111",
  "creditCardLastFour": "1111",
  "expirationMonthYear": "0828",
  "token": "jhlkjhlkh",
  "transactionReferenceCode": "hlksgdfhlgdkf"
}

Charge Payment Method

You should subscribe to commerce:charge event and write a handler to utilize this functionality. When Arc will send the following information to this integration to make an immediate charge to your customer’s tokenized payment method.

{
  "orderNumber": "AAAABBBBCCCCDDDD",
  "correlationId": "4d8c1b3c-b279-4ef5-bf40-db309c2cddac",
  "currency": "USD",
  "amount": "21.43",
  "token": "adshgfakjshdfgdsak"
}

You are expected to respond with either a negative response (see above) or a positive response in the following format:

{
  "transactionReferenceId": "kjdsfhalskjflsd"
}