Skip to main content

External payment flow via checkout webhook

Overview​

The external payment flow allows retailers to take full control of the payment process while maintaining seamless integration with the AiFi system. Through a set of APIs, AiFi enables retailers to decide whether an order is paid, unpaid, or still in process.

Payment integration via GPB is a more advanced integration option that allows retailers to fully control the payment process. It's recommended for retailers who need to integrate with external payment providers that require a more complex integration.

Journey​

  1. The shopper finishes the shopping journey and is ready to leave the store.
  2. AiFi triggers the checkout webhook configured by the retailer.
  3. The retailer's system receives the checkout payload and returns the payment status to AiFi:
    • paid
    • processing
    • unpaid
  4. If the status is processing, AiFi waits for the retailer to update the payment status later via the PATCH ORDER endpoint.

This approach ensures that the AiFi system reflects the real-time payment state managed by the retailer.

Developer integration flow​

Requirements​

Before you start, ensure that you have the following:

  • A sandbox environment created and shared with your development team or retailer.
  • A checkout webhook URL available, either from a deployed environment or a local setup exposed via a tunneling tool (for example, ngrok).
  • Access to the AiFi Console to configure the webhook.
note

If you don't have access, contact your Account Manager or Technical Product Manager.

Step 1: Configure the checkout webhook​

  1. Log in to the AiFi Console.
  2. Navigate to Webhooks and select Add webhook.
  3. Enter your Checkout webhook URL and set the webhook as Default (true).
note

When set as the default, AiFi expects a valid response from your endpoint during the checkout process.

Step 2: Test the checkout webhook​

If you're working in the sandbox environment, use the provided check-in and check-out scripts in the documentation to simulate the entire checkout process.

You can inspect both the request and response payloads to validate that the webhook behaves as expected.

Step 3: Handle payment status responses​

Your webhook response must include a valid paymentStatus. AiFi recognizes three primary statuses:

  • paid: Payment completed successfully.
  • processing: Payment in progress; AiFi will wait for an update.
  • unpaid: Payment failed or was declined.

If the endpoint fails or doesn't respond, AiFi uses a fallback state defined in the OASIS configuration (NONE_PAYMENT_STATUS). This variable reflects the default order status before payment confirmation.

Step 4: Update payment status​

If your system returns a paymentStatus of processing, AiFi will wait until you update the order status via the PATCH ORDER endpoint.

Example: Update order to unpaid​

curl --location --request PATCH 'https://oasis-api.public.sandbox.oasis.aifi.com/api/admin/v2/orders/12' \
--header 'Content-Type: application/json' \
--data '{
  "status": "unpaid"
}'

Example: Update order to paid​

curl --location --request PATCH 'https://oasis-api.public.sandbox.oasis.aifi.com/api/admin/v2/orders/12' \
--header 'Content-Type: application/json' \
--data '{
  "status": "paid"
}'

Step 5: Example checkout webhook payload​

{
  "externalId": null,
  "payment": {
    "paymentStatus": "processing",
    "paymentTransactionIds": [
      "eee4a7d5-d87d-4b94-9b75-89b39ef1f241-payment-id",
      "acd99831-22b6-47e1-9e51-f7f76d04ffcd-payment-id-2"
    ]
  }
}