Payments API

Execute a payment for a shopper with a saved payment method

POST /api/v1/payment

Required Parameters

• amount (number): The transaction amount in minor units. Must be a positive integer, greater than or equal to minimal amount and less than or equal to maximum amount.
• currency (string): The currency code for the transaction.
• merchantAccountId (string, optional*): The identifier for the merchant's account. Required if merchantReferenceId is not provided.
• referenceId (string, max 80 characters): A unique identifier for the checkout request. This should be persisted in your system to identify and match the corresponding transaction when a webhook notification is received. The referenceId ensures accurate tracking and reconciliation of transactions.
• shopperId (string): A unique identifier for the shopper with active saved payment methods, created during an initial checkout with savePaymentMethod flag. Shopper must belong to the same organization as the merchant account.
• recurringProcessingModel (enum - Subscription, UnscheduledCardOnFile) UnscheduledCardOnFile: A transaction that occurs on a non-fixed schedule and/or have variable amounts. Subscription: A transaction for a fixed or variable amount, which follows a fixed schedule.

Optional Parameters

• customAttributes (Record<string, string>, optional, max 80 characters per attribute): Custom data associated with the tansaction, displayed on the ui and returned in the payment webhook body. The list of possible keys is configured by the tenant.
• paymentMethodIdToken (string): This token uniquely identifies a payment method that has been saved by the merchant for future transactions. It is used to reference the specific payment method securely stored within the system, facilitating quick and secure transactions without the need to re-enter payment details.

Example: Process unscheduled card on file payment for $339.49 USD"

Request

{
  "referenceId": "v0lFEZW0uZegFTn",
  "amount": 33949,
  "currency": "USD",
  "merchantAccountId": "MERH4N6NUVZKZ",
  "shopperId": "ENOE2",
  "recurringProcessingModel": "UnscheduledCardOnFile",
  "customAttributes": {
    "INVOICE_ID": "1234"
  }
}

Successful Response

{
  "status": "ok",
  "data": {
    "resultCode": "Authorised"
  }
}

Get all payments (paginated)

Optional URL Query Parameters:

• status (string): Status or a comma-separated list of statuses.
• pspReferenceId (string): The unique reference ID for the payment service provider.
• paymentMethod (string): Payment method or a comma-separated list of payment methods.
• source (string): Source or a comma-separated list of sources.
• shopperEmail (string): Shopper's email address.
• selectedMerchantAccount (string): Selected merchant account.
• selectedOrganization (string): Selected organization.
• startDate (string): Start date in 'y-MM-dd' format.
• endDate (string): End date in 'y-MM-dd' format, inclusive of the day.
• pageSize (number): Number of records to return, max 1000.
• pageIndex (number): Page index beginning with 0.

GET /api/v1/payment

Response

{
  "status": "ok",
  "data": {
    "rows": [
      {
        "createdAt": "2024-06-08T23:49:40.257Z",
        "pspReferenceId": "GWBO29ULHGQQ2FKC",
        "merchantAccount": {
          "businessName": "Big Smile Europe"
        },
        "organization": {
          "name": "Big Smile LLC"
        },
        "authorizedAmount": 88311,
        "paymentMethod": "mc",
        "cardSummary": "1330",
        "source": "ECOMMERCE",
        "status": "DISPUTED"
      },
      {
        "createdAt": "2024-06-06T09:55:00.178Z",
        "pspReferenceId": "8BZDUOCT9YULAITD",
        "merchantAccount": {
          "businessName": "Big Smile LLC"
        },
        "organization": {
          "name": "Big Smile LLC"
        },
        "authorizedAmount": 59801,
        "paymentMethod": "discover",
        "cardSummary": "4851",
        "source": "ECOMMERCE",
        "status": "DISPUTED"
      },
      {
        "createdAt": "2024-06-06T06:54:20.536Z",
        "pspReferenceId": "YRKF1X8IUXEP-LDJ",
        "merchantAccount": {
          "businessName": "Big Smile Europe"
        },
        "organization": {
          "name": "Big Smile LLC"
        },
        "authorizedAmount": 96663,
        "paymentMethod": "visa",
        "cardSummary": "3769",
        "source": "ECOMMERCE",
        "status": "SETTLED"
      }
    ],
    "pagination": {
      "pageIndex": 0,
      "pageSize": 3,
      "pageCount": 34,
      "total": 100,
      "hasPrevPage": false,
      "hasNextPage": true
    }
  }
}

Get a payment by PSP reference id

GET /api/v1/payment?pspReferenceId=xxx232

Response

{
  "status": "ok",
  "data": {
    "pspReferenceId": "xxx232",
    "authorizedAmount": 24383,
    "surchargeAmount": 488,
    "refundedAmount": 0,
    "merchantSplitAmount": 23408,
    "tipAmount": null,
    "currency": "USD",
    "status": "DISPUTED",
    "paymentMethod": "mc",
    "paymentMethodVariant": "mcsuperpremiumdebit",
    "cardSummary": "1226",
    "splitSettingsFixed": 0,
    "splitSettingsPercentage": 300,
    "updatedAt": "2024-05-05T08:31:25.398Z",
    "createdAt": "2024-05-05T08:31:25.398Z",
    "reference": "cce9f7d6-f21f-45d1-b4a5-079cbf3581f2",
    "merchantAccountId": "0f922ad3-a5ca-4213-9d1b-f943e95831c4",
    "organizationId": "bf368afb-ed57-4345-a04a-7c7213431a99",
    "source": "ECOMMERCE",
    "merchantRefundedAmount": null,
    "tenantRefundedAmount": null,
    "merchantAccount": {
      "businessName": "Big Smile Europe",
      "splitConfigurationGroup": {
        "refundSplitModel": "REVERSE_PAYMENT_SPLIT"
      }
    },
    "organization": {
      "name": "Big Smile LLC"
    },
    "checkout": {
      "shopperId": null,
      "shopperFirstName": null,
      "shopperLastName": null,
      "shopperEmail": "K-gk3DmjiJl-xABMFb23k@example.com",
      "checkoutAttributes": [
        {
          "name": "INVOICE_ID",
          "value": "rwR42JRurM_WLua4qxoi4"
        }
      ]
    },
    "paymentEvents": [
      {
        "type": "SETTLEMENT",
        "status": "SETTLED",
        "amount": 24383,
        "currency": "USD",
        "pspReferenceId": "DNCUFNNV2JQACYE3",
        "createdAt": "2024-05-05T08:31:25.398Z"
      },
      {
        "type": "AUTHORIZATION",
        "status": "AUTHORIZED",
        "amount": 24383,
        "currency": "USD",
        "pspReferenceId": "DNCUFNNV2JQACYE3",
        "createdAt": "2024-05-05T08:31:25.398Z"
      }
    ]
  }
}