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): 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.

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