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