Skip to main content
API docs by Redocly

Payments API (v1.4.0)

Download OpenAPI specification:Download

Welcome to the Payments API documentation!

Introduction

This is the reference documentation and schemas for the Payments API.

Authentication

The platform uses API Keys to manage access to the API. You can pass the API key in the x-api-key header to the request. Talk you your sales rep about acquiring these API keys. Authorization is done via headers. You should pass the api key as the value to the x-api-key header. For example, x-api-key: ${API_KEY}. Please note that you will be given 2 API keys, one public key and one private key. Use the private key for all server to server communication. The public key is used for interfacing wih the JS SDK.

Idempotency

The platform provides support for idempotency, a feature that allows requests to be safely retried without the risk of duplicate operations. This becomes particularly useful when an API call is interrupted during transmission, resulting in the absence of a response.

To execute an idempotent request, include the idempotency key in the x-idempotency-key header of the request. This key, which should be a unique value of at least 10 characters, is generated by the client. The method of creating this key is up to you, but we recommend using UUID v4 or any other string that has sufficient entropy to prevent overlaps.

Idempotency works by saving the resulting status code and body of the first request made for any given idempotency key for any successful request. Subsequent requests with the same key return the same result for a period of up to 1 hour.

Idempotency is only supported for POST and PUT requests.

Checkout Sessions

Fetch list of checkout sessions for a given account

Use this endpoint to retrieve a paginated list of checkout sessions for a specific account. Checkout sessions are hosted payment forms that allow customers to complete payments. This endpoint is useful for monitoring session statuses, tracking conversion rates, and managing customer checkout experiences.

query Parameters
ending_before
string

The id of the entity, use to sort in reverse order

starting_after
string

The id of the entity

limit
number
Default: 10

Max value is 50

header Parameters
x-account-id
required
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a new checkout session

Use this endpoint to create a new hosted checkout session for customers. Checkout sessions provide a secure, branded payment experience where customers can enter payment information. You'll receive a URL that you can redirect customers to, and they'll be able to complete their payment securely.

header Parameters
x-account-id
required
string
x-idempotency-key
string
Request Body schema: application/json
cancel_url
string <= 500 characters
success_url
string <= 500 characters
customer_email
string <email> <= 255 characters
reference_id
string <= 300 characters
object
payment_method_types
Array of strings
Items Enum: "card" "bank"
required
object (PaymentIntentCreateRequestDTO)

Responses

Request samples

Content type
application/json
{
  • "cancel_url": "string",
  • "success_url": "string",
  • "customer_email": "user@example.com",
  • "reference_id": "string",
  • "user_fields": {
    },
  • "payment_method_types": [
    ],
  • "payment_intent_data": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "entity": "checkout_session",
  • "url": "string",
  • "cancel_url": "string",
  • "success_url": "string",
  • "customer_email": "string",
  • "reference_id": "string",
  • "user_fields": {
    },
  • "payment_method_types": [
    ],
  • "payment_intent_data": {
    },
  • "payment_intent_id": "string",
  • "status": "open",
  • "link_phone_number": "string",
  • "account_id": "string",
  • "partner_id": "string",
  • "business_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Fetch a specific checkout session

path Parameters
id
required
string
header Parameters
x-account-id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "entity": "checkout_session",
  • "url": "string",
  • "cancel_url": "string",
  • "success_url": "string",
  • "customer_email": "string",
  • "reference_id": "string",
  • "user_fields": {
    },
  • "payment_method_types": [
    ],
  • "payment_intent_data": {
    },
  • "payment_intent_id": "string",
  • "status": "open",
  • "link_phone_number": "string",
  • "account_id": "string",
  • "partner_id": "string",
  • "business_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Update a checkout session

path Parameters
id
required
string
header Parameters
x-account-id
required
string
x-idempotency-key
string
Request Body schema: application/json
customer_email
string <email> <= 255 characters
reference_id
string <= 300 characters
object
cancel_url
string <= 500 characters
success_url
string <= 500 characters
payment_method_types
Array of strings
Items Enum: "card" "bank"
object
subtotal
integer [ 0 .. 9007199254740991 ]
discount_amount
integer [ 0 .. 9007199254740991 ]

Responses

Request samples

Content type
application/json
{
  • "customer_email": "user@example.com",
  • "reference_id": "string",
  • "user_fields": {
    },
  • "cancel_url": "string",
  • "success_url": "string",
  • "payment_method_types": [
    ],
  • "payment_intent_data": {
    },
  • "subtotal": 9007199254740991,
  • "discount_amount": 9007199254740991
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "entity": "checkout_session",
  • "url": "string",
  • "cancel_url": "string",
  • "success_url": "string",
  • "customer_email": "string",
  • "reference_id": "string",
  • "user_fields": {
    },
  • "payment_method_types": [
    ],
  • "payment_intent_data": {
    },
  • "payment_intent_id": "string",
  • "status": "open",
  • "link_phone_number": "string",
  • "account_id": "string",
  • "partner_id": "string",
  • "business_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Fetch list of checkout session details

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "checkout_session": {
    },
  • "branding": {
    }
}

Expire a check session

path Parameters
id
required
string
header Parameters
x-account-id
required
string
x-idempotency-key
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "entity": "checkout_session",
  • "url": "string",
  • "cancel_url": "string",
  • "success_url": "string",
  • "customer_email": "string",
  • "reference_id": "string",
  • "user_fields": {
    },
  • "payment_method_types": [
    ],
  • "payment_intent_data": {
    },
  • "payment_intent_id": "string",
  • "status": "open",
  • "link_phone_number": "string",
  • "account_id": "string",
  • "partner_id": "string",
  • "business_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Create a checkout session payment

path Parameters
id
required
string
header Parameters
x-account-id
required
string
x-idempotency-key
string
Request Body schema: application/json
reference_id
string
object
description
string
object
cvv2
string
payment_method_id
required
string
object

Responses

Request samples

Content type
application/json
{
  • "reference_id": "string",
  • "user_fields": {
    },
  • "description": "string",
  • "order_details": {
    },
  • "cvv2": "string",
  • "payment_method_id": "string",
  • "billing_details": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "entity": "payment",
  • "status": "processing",
  • "billing_details": {
    },
  • "amount": 9007199254740991,
  • "amount_authorized": 9007199254740991,
  • "amount_captured": 9007199254740991,
  • "amount_refunded": 9007199254740991,
  • "amount_voided": 9007199254740991,
  • "amount_disputed": 9007199254740991,
  • "amount_reversed": 9007199254740991,
  • "amount_rejected": 9007199254740991,
  • "cvv": "M",
  • "avs": "A",
  • "address_line1_check": "pass",
  • "address_postal_code_check": "pass",
  • "cvv_check": "pass",
  • "signature": {
    },
  • "return_code": "string",
  • "return_message": "string",
  • "failure_code": "string",
  • "failure_message": "string",
  • "cancelled_at": "2019-08-24T14:15:22Z",
  • "cancel_reason": "string",
  • "decline_category": "string",
  • "decline_category_text": "string",
  • "emv_tag_data": "string",
  • "entry_mode": "keyed",
  • "reversed": true,
  • "reversal_id": "string",
  • "reversal_expected": true,
  • "disputed": true,
  • "dispute_id": "string",
  • "order_details": {
    },
  • "gateway_response": {
    },
  • "payment_intent_id": "string",
  • "payment_method_id": "string",
  • "payment_method": {
    },
  • "auth_code": "string",
  • "auth_response_text": "string",
  • "external": true,
  • "card_present": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "account_id": "string",
  • "reference_id": "string",
  • "user_fields": {
    },
  • "description": "string",
  • "settlement_status": "settled",
  • "settled_at": "string"
}

Send checkout session link via SMS

path Parameters
id
required
string
header Parameters
x-account-id
required
string
Request Body schema: application/json
phone_number
required
string^\+[1-9]\d{1,14}$

Phone number in E.164 format (e.g., +18883456789)

Responses

Request samples

Content type
application/json
{
  • "phone_number": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Send checkout session link via email

path Parameters
id
required
string
header Parameters
x-account-id
required
string
Request Body schema: application/json
cc_email_addresses
Array of strings <email>

Array of email addresses to send checkout session to

email_override
string <email>

Responses

Request samples

Content type
application/json
{
  • "cc_email_addresses": [
    ],
  • "email_override": "user@example.com"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Payment Intents

Create a payment intent

Use this endpoint to create a new payment intent. A payment intent represents a payment transaction and contains details such as amount, currency, and payment method types. This is the first step in processing a payment - you'll need the client_secret from the response to initialize the Payment Elements SDK.

header Parameters
x-account-id
required
string
x-idempotency-key
string
Request Body schema: application/json
amount
required
integer [ 0 .. 9007199254740991 ]
merchant_amount
integer [ 0 .. 9007199254740991 ]
Array of objects
object
capture
boolean
currency
string
Value: "USD"
reference_id
string <= 300 characters
object
description
string <= 1000 characters
payment_method_types
Array of strings
Items Enum: "card" "bank"

Responses

Request samples

Content type
application/json
{
  • "amount": 9007199254740991,
  • "merchant_amount": 9007199254740991,
  • "payment_splits": [
    ],
  • "order_details": {
    },
  • "capture": true,
  • "currency": "USD",
  • "reference_id": "string",
  • "user_fields": {
    },
  • "description": "string",
  • "payment_method_types": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "client_secret": "string",
  • "entity": "payment_intent",
  • "status": "created",
  • "amount": 9007199254740991,
  • "merchant_amount": 9007199254740991,
  • "amount_authorized": 9007199254740991,
  • "amount_captured": 9007199254740991,
  • "amount_refunded": 9007199254740991,
  • "amount_voided": 9007199254740991,
  • "amount_disputed": 9007199254740991,
  • "amount_reversed": 9007199254740991,
  • "amount_rejected": 9007199254740991,
  • "payment_splits": [
    ],
  • "order_details": {
    },
  • "capture": true,
  • "currency": "USD",
  • "latest_payment": {
    },
  • "disputed": true,
  • "dispute_id": "string",
  • "reversed": true,
  • "reversal_id": "string",
  • "external": true,
  • "partner_id": "string",
  • "business_id": "string",
  • "account_id": "string",
  • "payment_method_types": [
    ],
  • "reference_id": "string",
  • "user_fields": {
    },
  • "cancellation_reason": "string",
  • "description": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "cancelled_at": "2019-08-24T14:15:22Z",
  • "captured_at": "2019-08-24T14:15:22Z",
  • "settlement_status": "settled",
  • "settled_at": "2019-08-24T14:15:22Z"
}

Fetch a list of payment intents for an account

Use this endpoint to retrieve a paginated list of payment intents for a specific account. You can filter results using pagination parameters and optionally filter by business ID. This is useful for displaying transaction history or monitoring payment statuses.

query Parameters
ending_before
string

The id of the entity, use to sort in reverse order

starting_after
string

The id of the entity

limit
number
Default: 10

Max value is 50

header Parameters
x-account-id
string
x-business-id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Search for payment intents

Use this endpoint to search for payment intents using various criteria such as date ranges, amounts, statuses, or reference IDs. This is more flexible than the list endpoint and allows for complex filtering to find specific transactions.

header Parameters
x-account-id
string
x-business-id
string
Request Body schema: application/json
reference_id
string
status
string
Enum: "created" "processing" "pending" "uncaptured" "captured" "cancelled" "failed"
settlement_status
string
Enum: "settled" "unsettled"
payment_status
string
Enum: "processing" "pending" "uncaptured" "captured" "cancelled" "voided" "failed" "rejected"
has_refund
boolean
start_date
string <date-time>
Deprecated
end_date
string <date-time>
Deprecated
created_at_start
string <date-time>
created_at_end
string <date-time>
updated_at_start
string <date-time>
updated_at_end
string <date-time>
settled_at_start
string <date-time>
settled_at_end
string <date-time>
amount_min
integer
amount_max
integer
string or string or string or string or string or string or string
sort_direction
string
Enum: "asc" "desc"
limit
integer
page
integer

Responses

Request samples

Content type
application/json
{
  • "reference_id": "string",
  • "status": "created",
  • "settlement_status": "settled",
  • "payment_status": "processing",
  • "has_refund": true,
  • "start_date": "2019-08-24T14:15:22Z",
  • "end_date": "2019-08-24T14:15:22Z",
  • "created_at_start": "2019-08-24T14:15:22Z",
  • "created_at_end": "2019-08-24T14:15:22Z",
  • "updated_at_start": "2019-08-24T14:15:22Z",
  • "updated_at_end": "2019-08-24T14:15:22Z",
  • "settled_at_start": "2019-08-24T14:15:22Z",
  • "settled_at_end": "2019-08-24T14:15:22Z",
  • "amount_min": 0,
  • "amount_max": 0,
  • "sort_column": "amount",
  • "sort_direction": "asc",
  • "limit": 0,
  • "page": 0
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Fetch a payment intent for an account

path Parameters
id
required
string
header Parameters
x-account-id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "client_secret": "string",
  • "entity": "payment_intent",
  • "status": "created",
  • "amount": 9007199254740991,
  • "merchant_amount": 9007199254740991,
  • "amount_authorized": 9007199254740991,
  • "amount_captured": 9007199254740991,
  • "amount_refunded": 9007199254740991,
  • "amount_voided": 9007199254740991,
  • "amount_disputed": 9007199254740991,
  • "amount_reversed": 9007199254740991,
  • "amount_rejected": 9007199254740991,
  • "payment_splits": [
    ],
  • "order_details": {
    },
  • "capture": true,
  • "currency": "USD",
  • "latest_payment": {
    },
  • "disputed": true,
  • "dispute_id": "string",
  • "reversed": true,
  • "reversal_id": "string",
  • "external": true,
  • "partner_id": "string",
  • "business_id": "string",
  • "account_id": "string",
  • "payment_method_types": [
    ],
  • "reference_id": "string",
  • "user_fields": {
    },
  • "cancellation_reason": "string",
  • "description": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "cancelled_at": "2019-08-24T14:15:22Z",
  • "captured_at": "2019-08-24T14:15:22Z",
  • "settlement_status": "settled",
  • "settled_at": "2019-08-24T14:15:22Z"
}

Patch a payment intent

path Parameters
id
required
string
header Parameters
x-account-id
required
string
x-idempotency-key
string
Request Body schema: application/json
amount
integer [ 0 .. 9007199254740991 ]
merchant_amount
integer [ 0 .. 9007199254740991 ]
Array of objects
object
capture
boolean
payment_method_types
Array of strings
Items Enum: "card" "bank"
reference_id
string <= 300 characters
object
description
string <= 1000 characters

Responses

Request samples

Content type
application/json
{
  • "amount": 9007199254740991,
  • "merchant_amount": 9007199254740991,
  • "payment_splits": [
    ],
  • "order_details": {
    },
  • "capture": true,
  • "payment_method_types": [
    ],
  • "reference_id": "string",
  • "user_fields": {
    },
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "client_secret": "string",
  • "entity": "payment_intent",
  • "status": "created",
  • "amount": 9007199254740991,
  • "merchant_amount": 9007199254740991,
  • "amount_authorized": 9007199254740991,
  • "amount_captured": 9007199254740991,
  • "amount_refunded": 9007199254740991,
  • "amount_voided": 9007199254740991,
  • "amount_disputed": 9007199254740991,
  • "amount_reversed": 9007199254740991,
  • "amount_rejected": 9007199254740991,
  • "payment_splits": [
    ],
  • "order_details": {
    },
  • "capture": true,
  • "currency": "USD",
  • "latest_payment": {
    },
  • "disputed": true,
  • "dispute_id": "string",
  • "reversed": true,
  • "reversal_id": "string",
  • "external": true,
  • "partner_id": "string",
  • "business_id": "string",
  • "account_id": "string",
  • "payment_method_types": [
    ],
  • "reference_id": "string",
  • "user_fields": {
    },
  • "cancellation_reason": "string",
  • "description": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "cancelled_at": "2019-08-24T14:15:22Z",
  • "captured_at": "2019-08-24T14:15:22Z",
  • "settlement_status": "settled",
  • "settled_at": "2019-08-24T14:15:22Z"
}

Cancel a payment intent

path Parameters
id
required
string
header Parameters
x-account-id
required
string
x-idempotency-key
string
Request Body schema: application/json
cancellation_reason
string
Enum: "duplicate" "fraudulent" "requested_by_customer" "abandoned"

Responses

Request samples

Content type
application/json
{
  • "cancellation_reason": "duplicate"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "client_secret": "string",
  • "entity": "payment_intent",
  • "status": "created",
  • "amount": 9007199254740991,
  • "merchant_amount": 9007199254740991,
  • "amount_authorized": 9007199254740991,
  • "amount_captured": 9007199254740991,
  • "amount_refunded": 9007199254740991,
  • "amount_voided": 9007199254740991,
  • "amount_disputed": 9007199254740991,
  • "amount_reversed": 9007199254740991,
  • "amount_rejected": 9007199254740991,
  • "payment_splits": [
    ],
  • "order_details": {
    },
  • "capture": true,
  • "currency": "USD",
  • "latest_payment": {
    },
  • "disputed": true,
  • "dispute_id": "string",
  • "reversed": true,
  • "reversal_id": "string",
  • "external": true,
  • "partner_id": "string",
  • "business_id": "string",
  • "account_id": "string",
  • "payment_method_types": [
    ],
  • "reference_id": "string",
  • "user_fields": {
    },
  • "cancellation_reason": "string",
  • "description": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "cancelled_at": "2019-08-24T14:15:22Z",
  • "captured_at": "2019-08-24T14:15:22Z",
  • "settlement_status": "settled",
  • "settled_at": "2019-08-24T14:15:22Z"
}

Capture a payment intent

path Parameters
id
required
string
header Parameters
x-account-id
required
string
x-idempotency-key
string
Request Body schema: application/json
amount
integer (Amount to capture) >= 0

Amount charged to the cardholder

merchant_amount
integer (Merchant Amount) >= 0

Amount to be credited to the merchant (Advanced Plan only)

object
Array of objects

Responses

Request samples

Content type
application/json
{
  • "amount": 0,
  • "merchant_amount": 0,
  • "payment_data": {
    },
  • "payment_splits": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "client_secret": "string",
  • "entity": "payment_intent",
  • "status": "created",
  • "amount": 9007199254740991,
  • "merchant_amount": 9007199254740991,
  • "amount_authorized": 9007199254740991,
  • "amount_captured": 9007199254740991,
  • "amount_refunded": 9007199254740991,
  • "amount_voided": 9007199254740991,
  • "amount_disputed": 9007199254740991,
  • "amount_reversed": 9007199254740991,
  • "amount_rejected": 9007199254740991,
  • "payment_splits": [
    ],
  • "order_details": {
    },
  • "capture": true,
  • "currency": "USD",
  • "latest_payment": {
    },
  • "disputed": true,
  • "dispute_id": "string",
  • "reversed": true,
  • "reversal_id": "string",
  • "external": true,
  • "partner_id": "string",
  • "business_id": "string",
  • "account_id": "string",
  • "payment_method_types": [
    ],
  • "reference_id": "string",
  • "user_fields": {
    },
  • "cancellation_reason": "string",
  • "description": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "cancelled_at": "2019-08-24T14:15:22Z",
  • "captured_at": "2019-08-24T14:15:22Z",
  • "settlement_status": "settled",
  • "settled_at": "2019-08-24T14:15:22Z"
}

Fetch list of payments for a payment intent

path Parameters
id
required
string
query Parameters
ending_before
string

The id of the entity, use to sort in reverse order

starting_after
string

The id of the entity

limit
number
Default: 10

Max value is 50

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a payment

path Parameters
id
required
string
header Parameters
x-account-id
required
string
x-idempotency-key
string
Request Body schema: application/json
reference_id
string
object
description
string
object
cvv2
string
payment_method_id
required
string
object

Responses

Request samples

Content type
application/json
{
  • "reference_id": "string",
  • "user_fields": {
    },
  • "description": "string",
  • "order_details": {
    },
  • "cvv2": "string",
  • "payment_method_id": "string",
  • "billing_details": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "entity": "payment",
  • "status": "processing",
  • "billing_details": {
    },
  • "amount": 9007199254740991,
  • "amount_authorized": 9007199254740991,
  • "amount_captured": 9007199254740991,
  • "amount_refunded": 9007199254740991,
  • "amount_voided": 9007199254740991,
  • "amount_disputed": 9007199254740991,
  • "amount_reversed": 9007199254740991,
  • "amount_rejected": 9007199254740991,
  • "cvv": "M",
  • "avs": "A",
  • "address_line1_check": "pass",
  • "address_postal_code_check": "pass",
  • "cvv_check": "pass",
  • "signature": {
    },
  • "return_code": "string",
  • "return_message": "string",
  • "failure_code": "string",
  • "failure_message": "string",
  • "cancelled_at": "2019-08-24T14:15:22Z",
  • "cancel_reason": "string",
  • "decline_category": "string",
  • "decline_category_text": "string",
  • "emv_tag_data": "string",
  • "entry_mode": "keyed",
  • "reversed": true,
  • "reversal_id": "string",
  • "reversal_expected": true,
  • "disputed": true,
  • "dispute_id": "string",
  • "order_details": {
    },
  • "gateway_response": {
    },
  • "payment_intent_id": "string",
  • "payment_method_id": "string",
  • "payment_method": {
    },
  • "auth_code": "string",
  • "auth_response_text": "string",
  • "external": true,
  • "card_present": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "account_id": "string",
  • "reference_id": "string",
  • "user_fields": {
    },
  • "description": "string",
  • "settlement_status": "settled",
  • "settled_at": "string"
}

Create a refund

Use this endpoint to create a refund for a completed payment. You can issue full or partial refunds, and specify a reason for the refund. Refunds can be processed immediately or scheduled for later processing depending on your business needs and the payment method used.

path Parameters
id
required
string
header Parameters
x-account-id
required
string
x-idempotency-key
string
Request Body schema: application/json
amount
integer [ 0 .. 9007199254740991 ]
Array of objects

Responses

Request samples

Content type
application/json
{
  • "amount": 9007199254740991,
  • "refund_splits": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "entity": "refund",
  • "status": "pending",
  • "external": true,
  • "amount": 9007199254740991,
  • "account_id": "string",
  • "payment_id": "string",
  • "refund_splits": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "settlement_status": "settled",
  • "settled_at": "string"
}

Refunds

Fetch a refund by id

Use this endpoint to retrieve details about a specific refund by its ID. This returns information about the refund including amount, status, reason, and processing details. Useful for tracking refund statuses and providing customer support.

path Parameters
id
required
string
header Parameters
x-account-id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "entity": "refund",
  • "status": "pending",
  • "external": true,
  • "amount": 9007199254740991,
  • "account_id": "string",
  • "payment_id": "string",
  • "refund_splits": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "settlement_status": "settled",
  • "settled_at": "string"
}

Payment Methods

Fetch payment method

Use this endpoint to retrieve details about a specific payment method by its ID. This returns information about stored payment methods including card details, billing information, and validation status. Useful for displaying saved payment methods to customers or verifying payment method details.

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "entity": "payment_method",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "payment_method_type": "bank",
  • "source_type": "cardpointe",
  • "billing_details": {
    },
  • "payment_intent_id": "string",
  • "payment_method_intent_id": "string",
  • "single_use_token": true,
  • "signature": "string",
  • "bank": {
    },
  • "meta_data": {
    },
  • "validation_response": {
    }
}

Update payment method

Use this endpoint to update an existing payment method's information such as billing details, card expiration dates, or contact information. This is useful when customers need to update their payment method details or when you need to refresh expired card information.

path Parameters
id
required
string
Request Body schema: application/json
object
object
object

Responses

Request samples

Content type
application/json
{
  • "billing_details": {
    },
  • "card": {
    },
  • "meta_data": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "entity": "payment_method",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "payment_method_type": "bank",
  • "source_type": "cardpointe",
  • "billing_details": {
    },
  • "payment_intent_id": "string",
  • "payment_method_intent_id": "string",
  • "single_use_token": true,
  • "signature": "string",
  • "bank": {
    },
  • "meta_data": {
    },
  • "validation_response": {
    }
}

External Payments

Create External Payment Intent

Use this endpoint to create an external payment intent for processing payments through external gateways or terminals. This is useful when you need to integrate with third-party payment systems or when processing payments outside of the standard Forward payment flow.

header Parameters
x-account-id
required
string
x-idempotency-key
string
Request Body schema: application/json
required
object
required
object
object
required
object
card_present
boolean

Responses

Request samples

Content type
application/json
{
  • "payment_intent": {
    },
  • "payment_method": {
    },
  • "payment": {
    },
  • "gateway_response": {
    },
  • "card_present": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "client_secret": "string",
  • "entity": "payment_intent",
  • "status": "created",
  • "amount": 9007199254740991,
  • "merchant_amount": 9007199254740991,
  • "amount_authorized": 9007199254740991,
  • "amount_captured": 9007199254740991,
  • "amount_refunded": 9007199254740991,
  • "amount_voided": 9007199254740991,
  • "amount_disputed": 9007199254740991,
  • "amount_reversed": 9007199254740991,
  • "amount_rejected": 9007199254740991,
  • "payment_splits": [
    ],
  • "order_details": {
    },
  • "capture": true,
  • "currency": "USD",
  • "latest_payment": {
    },
  • "disputed": true,
  • "dispute_id": "string",
  • "reversed": true,
  • "reversal_id": "string",
  • "external": true,
  • "partner_id": "string",
  • "business_id": "string",
  • "account_id": "string",
  • "payment_method_types": [
    ],
  • "reference_id": "string",
  • "user_fields": {
    },
  • "cancellation_reason": "string",
  • "description": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "cancelled_at": "2019-08-24T14:15:22Z",
  • "captured_at": "2019-08-24T14:15:22Z",
  • "settlement_status": "settled",
  • "settled_at": "2019-08-24T14:15:22Z"
}

Update External Payment Intent

path Parameters
payment_intent_id
required
string
header Parameters
x-account-id
required
string
x-idempotency-key
string
Request Body schema: application/json
amount
integer <= 9007199254740991
merchant_amount
integer <= 9007199254740991
object (ExternalPaymentMethodCreateRequestDTO)
object
card_present
boolean

Responses

Request samples

Content type
application/json
{
  • "amount": 9007199254740991,
  • "merchant_amount": 9007199254740991,
  • "payment_method": {
    },
  • "gateway_response": {
    },
  • "card_present": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "client_secret": "string",
  • "entity": "payment_intent",
  • "status": "created",
  • "amount": 9007199254740991,
  • "merchant_amount": 9007199254740991,
  • "amount_authorized": 9007199254740991,
  • "amount_captured": 9007199254740991,
  • "amount_refunded": 9007199254740991,
  • "amount_voided": 9007199254740991,
  • "amount_disputed": 9007199254740991,
  • "amount_reversed": 9007199254740991,
  • "amount_rejected": 9007199254740991,
  • "payment_splits": [
    ],
  • "order_details": {
    },
  • "capture": true,
  • "currency": "USD",
  • "latest_payment": {
    },
  • "disputed": true,
  • "dispute_id": "string",
  • "reversed": true,
  • "reversal_id": "string",
  • "external": true,
  • "partner_id": "string",
  • "business_id": "string",
  • "account_id": "string",
  • "payment_method_types": [
    ],
  • "reference_id": "string",
  • "user_fields": {
    },
  • "cancellation_reason": "string",
  • "description": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "cancelled_at": "2019-08-24T14:15:22Z",
  • "captured_at": "2019-08-24T14:15:22Z",
  • "settlement_status": "settled",
  • "settled_at": "2019-08-24T14:15:22Z"
}

Cancel Payment Intent

path Parameters
payment_intent_id
required
string
header Parameters
x-account-id
required
string
x-idempotency-key
string
Request Body schema: application/json
object
cancellation_reason
string
Enum: "duplicate" "fraudulent" "requested_by_customer" "abandoned"

Responses

Request samples

Content type
application/json
{
  • "gateway_void_response": {
    },
  • "cancellation_reason": "duplicate"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "client_secret": "string",
  • "entity": "payment_intent",
  • "status": "created",
  • "amount": 9007199254740991,
  • "merchant_amount": 9007199254740991,
  • "amount_authorized": 9007199254740991,
  • "amount_captured": 9007199254740991,
  • "amount_refunded": 9007199254740991,
  • "amount_voided": 9007199254740991,
  • "amount_disputed": 9007199254740991,
  • "amount_reversed": 9007199254740991,
  • "amount_rejected": 9007199254740991,
  • "payment_splits": [
    ],
  • "order_details": {
    },
  • "capture": true,
  • "currency": "USD",
  • "latest_payment": {
    },
  • "disputed": true,
  • "dispute_id": "string",
  • "reversed": true,
  • "reversal_id": "string",
  • "external": true,
  • "partner_id": "string",
  • "business_id": "string",
  • "account_id": "string",
  • "payment_method_types": [
    ],
  • "reference_id": "string",
  • "user_fields": {
    },
  • "cancellation_reason": "string",
  • "description": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "cancelled_at": "2019-08-24T14:15:22Z",
  • "captured_at": "2019-08-24T14:15:22Z",
  • "settlement_status": "settled",
  • "settled_at": "2019-08-24T14:15:22Z"
}

Capture External Payment

path Parameters
payment_intent_id
required
string
header Parameters
x-account-id
required
string
x-idempotency-key
string
Request Body schema: application/json
amount
integer <= 9007199254740991
required
object

Responses

Request samples

Content type
application/json
{
  • "amount": 9007199254740991,
  • "gateway_capture_response": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "client_secret": "string",
  • "entity": "payment_intent",
  • "status": "created",
  • "amount": 9007199254740991,
  • "merchant_amount": 9007199254740991,
  • "amount_authorized": 9007199254740991,
  • "amount_captured": 9007199254740991,
  • "amount_refunded": 9007199254740991,
  • "amount_voided": 9007199254740991,
  • "amount_disputed": 9007199254740991,
  • "amount_reversed": 9007199254740991,
  • "amount_rejected": 9007199254740991,
  • "payment_splits": [
    ],
  • "order_details": {
    },
  • "capture": true,
  • "currency": "USD",
  • "latest_payment": {
    },
  • "disputed": true,
  • "dispute_id": "string",
  • "reversed": true,
  • "reversal_id": "string",
  • "external": true,
  • "partner_id": "string",
  • "business_id": "string",
  • "account_id": "string",
  • "payment_method_types": [
    ],
  • "reference_id": "string",
  • "user_fields": {
    },
  • "cancellation_reason": "string",
  • "description": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "cancelled_at": "2019-08-24T14:15:22Z",
  • "captured_at": "2019-08-24T14:15:22Z",
  • "settlement_status": "settled",
  • "settled_at": "2019-08-24T14:15:22Z"
}

External Refunds

Create External Refund

header Parameters
x-account-id
required
string
x-idempotency-key
string
Request Body schema: application/json
payment_intent_id
required
string
object (RefundRequestDTO)
required
object

Responses

Request samples

Content type
application/json
{
  • "payment_intent_id": "string",
  • "refund_request": {
    },
  • "gateway_response": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "entity": "refund",
  • "status": "pending",
  • "external": true,
  • "amount": 9007199254740991,
  • "account_id": "string",
  • "payment_id": "string",
  • "refund_splits": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "settlement_status": "settled",
  • "settled_at": "string"
}

Update External Refund

path Parameters
refund_id
required
string
header Parameters
x-account-id
required
string
x-idempotency-key
string
Request Body schema: application/json
payment_intent_id
required
string
object (RefundRequestDTO)
required
object

Responses

Request samples

Content type
application/json
{
  • "payment_intent_id": "string",
  • "refund_request": {
    },
  • "gateway_response": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "entity": "refund",
  • "status": "pending",
  • "external": true,
  • "amount": 9007199254740991,
  • "account_id": "string",
  • "payment_id": "string",
  • "refund_splits": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "settlement_status": "settled",
  • "settled_at": "string"
}

Cancel External Refund

path Parameters
refund_id
required
string
header Parameters
x-account-id
required
string
x-idempotency-key
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "entity": "refund",
  • "status": "pending",
  • "external": true,
  • "amount": 9007199254740991,
  • "account_id": "string",
  • "payment_id": "string",
  • "refund_splits": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "settlement_status": "settled",
  • "settled_at": "string"
}

Disputes

Fetch list of disputes matching query

Use this endpoint to retrieve a list of payment disputes that match your query criteria. You can filter disputes by status, date ranges, and other parameters. This is essential for monitoring chargebacks, managing customer disputes, and maintaining compliance with payment network requirements.

query Parameters
starting_after
string
ending_before
string
string or string or string or string or string or string
limit
number <= 50
Default: 10

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Fetch dispute by id

Use this endpoint to retrieve detailed information about a specific dispute by its ID. This returns comprehensive dispute information including evidence, timeline, amounts, and current status. Essential for responding to disputes and managing the dispute resolution process.

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "entity": "dispute",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "account_id": "string",
  • "business_id": "string",
  • "status": "new",
  • "payment_id": "string",
  • "payment_intent_id": "string",
  • "amount": 9007199254740991,
  • "notes": [
    ],
  • "attachments": [
    ],
  • "dispute_date": "2019-08-24",
  • "response_due_date": "2019-08-24",
  • "closed_date": "2019-08-24",
  • "reason_disputed_code": 0,
  • "reason_disputed": "string",
  • "dispute_response": "string",
  • "reference_meta": {
    },
  • "settlement_status": "settled",
  • "settled_at": "string"
}

Balances

Fetch ledger account balances

Use this endpoint to retrieve current balance information for ledger accounts. This provides real-time visibility into account balances, pending amounts, and available funds. Essential for financial reporting, reconciliation, and understanding your current financial position.

query Parameters
ledger_type
string
Enum: "operating" "funding"
currency
string
Value: "USD"

Responses

Response samples

Content type
application/json
{
  • "currency": "USD",
  • "pending": 9007199254740991,
  • "available": 9007199254740991
}

Transactions

Fetch a list of transactions

Use this endpoint to retrieve a paginated list of transactions for an account. This includes all financial activities such as payments, refunds, fees, and transfers. Essential for financial reporting, reconciliation, and understanding your transaction history.

query Parameters
ending_before
string
starting_after
string
limit
number
payout_id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Fetch a transaction

Use this endpoint to retrieve detailed information about a specific transaction by its ID. This returns comprehensive transaction details including amounts, status, timestamps, and associated metadata. Useful for transaction verification and customer support.

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "entity": "transaction",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "ledger_account_id": "string",
  • "payout_id": "string",
  • "bank_transfer_id": "string",
  • "source_type": "dispute",
  • "source_id": "string",
  • "source_account_id": "string",
  • "root_source_id": "string",
  • "root_source_type": "adjustment",
  • "amount": 9007199254740991,
  • "settlement_id": "string",
  • "settlement_status": "settled",
  • "settled_at": "string",
  • "description": "string",
  • "historical_bank_transfer_ids": [
    ],
  • "historical_payout_ids": [
    ]
}

Search a list of transactions

Use this endpoint to search for transactions using various criteria such as date ranges, amounts, statuses, or reference IDs. This provides more flexible filtering than the list endpoint and allows for complex queries to find specific transactions or generate custom reports.

Request Body schema: application/json
root_source_id
string

The root source ID of the transaction, typically the ID of a payment, refund or dispute. For example, passing a payment id will return all balance transactions that are related to that payment (fees, transfers, etc.).

source_type
string
Enum: "dispute" "fee" "fee_refund" "funding" "payment" "payment_method" "payout" "refund" "refund_failure" "transfer" "reversal" "transaction"
settlement_status
string
Enum: "settled" "unsettled"
start_date
string <date-time>
Deprecated
end_date
string <date-time>
Deprecated
created_at_start
string <date-time>
created_at_end
string <date-time>
updated_at_start
string <date-time>
updated_at_end
string <date-time>
settled_at_start
string <date-time>
settled_at_end
string <date-time>
string or string or string or string or string
Default: "updated_at"
sort_direction
string
Enum: "asc" "desc"
amount_min
integer
amount_max
integer
limit
integer <= 50
Default: 10
page
integer >= 1
Default: 1

Responses

Request samples

Content type
application/json
{
  • "root_source_id": "string",
  • "source_type": "dispute",
  • "settlement_status": "settled",
  • "start_date": "2019-08-24T14:15:22Z",
  • "end_date": "2019-08-24T14:15:22Z",
  • "created_at_start": "2019-08-24T14:15:22Z",
  • "created_at_end": "2019-08-24T14:15:22Z",
  • "updated_at_start": "2019-08-24T14:15:22Z",
  • "updated_at_end": "2019-08-24T14:15:22Z",
  • "settled_at_start": "2019-08-24T14:15:22Z",
  • "settled_at_end": "2019-08-24T14:15:22Z",
  • "sort_column": "updated_at",
  • "sort_direction": "asc",
  • "amount_min": 0,
  • "amount_max": 0,
  • "limit": 10,
  • "page": 1
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Download list of transactions

Request Body schema: application/json
root_source_id
string

The root source ID of the transaction, typically the ID of a payment, refund or dispute. For example, passing a payment id will return all balance transactions that are related to that payment (fees, transfers, etc.).

source_type
string
Enum: "dispute" "fee" "fee_refund" "funding" "payment" "payment_method" "payout" "refund" "refund_failure" "transfer" "reversal" "transaction"
settlement_status
string
Enum: "settled" "unsettled"
start_date
string <date-time>
Deprecated
end_date
string <date-time>
Deprecated
created_at_start
string <date-time>
created_at_end
string <date-time>
updated_at_start
string <date-time>
updated_at_end
string <date-time>
settled_at_start
string <date-time>
settled_at_end
string <date-time>
string or string or string or string or string
Default: "updated_at"
sort_direction
string
Enum: "asc" "desc"
amount_min
integer
amount_max
integer

Responses

Request samples

Content type
application/json
{
  • "root_source_id": "string",
  • "source_type": "dispute",
  • "settlement_status": "settled",
  • "start_date": "2019-08-24T14:15:22Z",
  • "end_date": "2019-08-24T14:15:22Z",
  • "created_at_start": "2019-08-24T14:15:22Z",
  • "created_at_end": "2019-08-24T14:15:22Z",
  • "updated_at_start": "2019-08-24T14:15:22Z",
  • "updated_at_end": "2019-08-24T14:15:22Z",
  • "settled_at_start": "2019-08-24T14:15:22Z",
  • "settled_at_end": "2019-08-24T14:15:22Z",
  • "sort_column": "updated_at",
  • "sort_direction": "asc",
  • "amount_min": 0,
  • "amount_max": 0
}

Response samples

Content type
application/json
{ }

Payouts

Fetch a list of payouts

Use this endpoint to retrieve a paginated list of payouts for an account. Payouts represent funds being transferred from your Forward account to your bank account. You can filter by status to monitor payout processing, track completed transfers, and manage your cash flow.

query Parameters
ending_before
string
starting_after
string
limit
number
string or string or string or string or string or string or string or string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Fetch a payout by id

Use this endpoint to retrieve detailed information about a specific payout by its ID. This returns comprehensive payout details including status, amounts, processing dates, and bank transfer information. Essential for tracking individual payout statuses and reconciling bank deposits.

path Parameters
id
required
string
query Parameters
ledger_type
string
Enum: "operating" "funding"
currency
string
Value: "USD"
header Parameters
x-account-id
string

Required when fetching a payout associated with an account, exclude if fetching your own payout

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "entity": "payout",
  • "status": "created",
  • "payout_number": 0,
  • "transaction_count": 0,
  • "transaction_summary": [
    ],
  • "amount": 9007199254740991,
  • "net_amount": 9007199254740991,
  • "fee_amount": 9007199254740991,
  • "batch_fee": 9007199254740991,
  • "reject_fee": 9007199254740991,
  • "latest_payment_data": {
    },
  • "payment_data": [
    ],
  • "payment_attempt_count": 0,
  • "payment_reject_count": 0,
  • "owner_type": "account",
  • "owner_id": "string",
  • "ledger_type": "operating",
  • "currency": "USD",
  • "business_id": "string",
  • "batch_window": {
    },
  • "settlement_status": "settled",
  • "settled_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "returned_at": "2019-08-24T14:15:22Z"
}

Fetch a list of payouts for a business

query Parameters
ending_before
string

The id of the entity, use to sort in reverse order

starting_after
string

The id of the entity

limit
number
Default: 10

Max value is 50

header Parameters
x-business-id
required
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Payment Method Intents

Create a payment method intent

Use this endpoint to create a new payment method intent for securely collecting and validating payment method information. Payment method intents provide a secure way to collect card or bank account details from customers. You can create them with or without payment method data, and they support validation to ensure the payment method is valid before storing.

header Parameters
x-account-id
required
string
x-idempotency-key
string
Request Body schema: application/json
object or object
payment_method_types
Array of strings
Items Enum: "card" "bank"
object
validate
boolean
string or string

Responses

Request samples

Content type
application/json
{
  • "payment_method_data": {
    },
  • "payment_method_types": [
    ],
  • "user_fields": {
    },
  • "validate": true,
  • "bill_to": "merchant"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "client_secret": "string",
  • "entity": "payment_method_intent",
  • "status": "created",
  • "account_id": "string",
  • "payment_method_types": [
    ],
  • "payment_method": {
    },
  • "validate": true,
  • "bill_to": "merchant",
  • "latest_validation_response": {
    },
  • "validation_attempts": [
    ],
  • "user_fields": {
    },
  • "cancellation_reason": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Fetch a payment method intents

Use this endpoint to retrieve a paginated list of payment method intents for an account. This is useful for monitoring the status of payment method creation requests, tracking validation attempts, and managing the lifecycle of payment method setup processes.

query Parameters
ending_before
string

The id of the entity, use to sort in reverse order

starting_after
string

The id of the entity

limit
number
Default: 10

Max value is 50

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Fetch a payment method intent

Use this endpoint to retrieve details about a specific payment method intent by its ID. This returns information about the payment method creation process, validation status, and any associated payment method data. Useful for checking the status of a payment method setup request.

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "client_secret": "string",
  • "entity": "payment_method_intent",
  • "status": "created",
  • "account_id": "string",
  • "payment_method_types": [
    ],
  • "payment_method": {
    },
  • "validate": true,
  • "bill_to": "merchant",
  • "latest_validation_response": {
    },
  • "validation_attempts": [
    ],
  • "user_fields": {
    },
  • "cancellation_reason": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a payment method intent

path Parameters
id
required
string
Request Body schema: application/json
object
payment_method_types
Array of strings
Items Enum: "card" "bank"

Responses

Request samples

Content type
application/json
{
  • "user_fields": {
    },
  • "payment_method_types": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "client_secret": "string",
  • "entity": "payment_method_intent",
  • "status": "created",
  • "account_id": "string",
  • "payment_method_types": [
    ],
  • "payment_method": {
    },
  • "validate": true,
  • "bill_to": "merchant",
  • "latest_validation_response": {
    },
  • "validation_attempts": [
    ],
  • "user_fields": {
    },
  • "cancellation_reason": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Cancel a payment method intent

path Parameters
id
required
string
Request Body schema: application/json
cancellation_reason
string

Responses

Request samples

Content type
application/json
{
  • "cancellation_reason": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "client_secret": "string",
  • "entity": "payment_method_intent",
  • "status": "created",
  • "account_id": "string",
  • "payment_method_types": [
    ],
  • "payment_method": {
    },
  • "validate": true,
  • "bill_to": "merchant",
  • "latest_validation_response": {
    },
  • "validation_attempts": [
    ],
  • "user_fields": {
    },
  • "cancellation_reason": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Fees

Fetch a list of fees.

Use this endpoint to retrieve a paginated list of fees for a merchant account. Fees represent various charges including processing fees, interchange fees, monthly minimums, and adhoc fees. You can filter by fee type, source, and date ranges to understand your cost structure and track fee-related transactions.

query Parameters
ending_before
string
starting_after
string
limit
number or null >= 0
fee_type
string
Enum: "APPLICATION" "BATCH" "CHARGEBACK" "INTERCHANGE" "PLATFORM" "TOKEN" "PROCESSING" "RETRIEVAL" "DDA_REJECT" "MONTHLY_MINIMUM" "PCI_NON_COMPLIANCE" "GATEWAY_FEE" "EARLY_CANCELLATION" "REGULATORY_PRODUCT" "VALIDATION_FEE" "LINKING_FEE" "REJECT_FEE" "REVERSAL_FEE" "UNKNOWN_BANK_ACTIVITY_ADJUSTMENT" "UNMATCHED_SETTLEMENT" "PARTNER_ADHOC"
source_id
string

Filter fees by source_id. Examples: A fee refund has a source_id of the original fee it is refunding. A processing fee has a source id of the payment.

header Parameters
x-account-id
required
string or null

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create an adhoc fee.

Create an adhoc fee for a merchant account. Fee refunds through this endpoint will be deprecated, please use the /fees/:id/refund endpoint instead.

header Parameters
x-account-id
required
string or null
Request Body schema: application/json

Body

amount
required
integer or null >= 0
description
required
string <= 1000 characters
payment_id
string or null
reference_id
string <= 300 characters
object
is_refund
boolean

(Deprecated) By default, 'is_refund' is false, so the fee amount is charged to the merchant. When set to true, the amount is refunded to the merchant. Note: A 'payment_id' or 'fee_id' is required for all fee refunds.

Responses

Request samples

Content type
application/json
{
  • "amount": 0,
  • "description": "string",
  • "payment_id": "string",
  • "reference_id": "string",
  • "user_fields": {
    },
  • "is_refund": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "entity": "fee",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "fee_type": "APPLICATION",
  • "fee_sub_type": "auth",
  • "description": "string",
  • "from_owner_id": "string",
  • "from_owner_type": "account",
  • "to_owner_id": "string",
  • "to_owner_type": "account",
  • "source_type": "adjustment",
  • "source_id": "string",
  • "source_account_id": "string",
  • "amount": 0,
  • "amount_refunded": 0,
  • "auth_fee": 0,
  • "card_fee_bps": 0,
  • "ach_per_transaction_fee": 0,
  • "ach_fee_bps": 0,
  • "ach_bps_fee_max": 0,
  • "ach_service_type": "standard",
  • "card_type": "visa",
  • "settlement_id": "string",
  • "settlement_status": "settled",
  • "settled_at": "2019-08-24T14:15:22Z",
  • "monthly_fee_date": "string",
  • "reference_id": "string",
  • "user_fields": {
    },
  • "is_refund": true
}

Fetch a fee by id.

Fetch a fee by id for a merchant account

path Parameters
id
required
string or null
header Parameters
x-account-id
required
string or null

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "entity": "fee",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "fee_type": "APPLICATION",
  • "fee_sub_type": "auth",
  • "description": "string",
  • "from_owner_id": "string",
  • "from_owner_type": "account",
  • "to_owner_id": "string",
  • "to_owner_type": "account",
  • "source_type": "adjustment",
  • "source_id": "string",
  • "source_account_id": "string",
  • "amount": 0,
  • "amount_refunded": 0,
  • "auth_fee": 0,
  • "card_fee_bps": 0,
  • "ach_per_transaction_fee": 0,
  • "ach_fee_bps": 0,
  • "ach_bps_fee_max": 0,
  • "ach_service_type": "standard",
  • "card_type": "visa",
  • "settlement_id": "string",
  • "settlement_status": "settled",
  • "settled_at": "2019-08-24T14:15:22Z",
  • "monthly_fee_date": "string",
  • "reference_id": "string",
  • "user_fields": {
    },
  • "is_refund": true
}

Refund an adhoc fee.

Partially or fully refund an adhoc fee up to the amount of the original fee. If partially refunding a fee, there is a limit of 10 refunds per fee.

path Parameters
id
required
string or null
Request Body schema: application/json

Body

amount
required
integer or null >= 0
description
required
string <= 1000 characters
reference_id
string <= 300 characters
object

Responses

Request samples

Content type
application/json
{
  • "amount": 0,
  • "description": "string",
  • "reference_id": "string",
  • "user_fields": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "entity": "fee",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "fee_type": "APPLICATION",
  • "fee_sub_type": "auth",
  • "description": "string",
  • "from_owner_id": "string",
  • "from_owner_type": "account",
  • "to_owner_id": "string",
  • "to_owner_type": "account",
  • "source_type": "adjustment",
  • "source_id": "string",
  • "source_account_id": "string",
  • "amount": 0,
  • "amount_refunded": 0,
  • "auth_fee": 0,
  • "card_fee_bps": 0,
  • "ach_per_transaction_fee": 0,
  • "ach_fee_bps": 0,
  • "ach_bps_fee_max": 0,
  • "ach_service_type": "standard",
  • "card_type": "visa",
  • "settlement_id": "string",
  • "settlement_status": "settled",
  • "settled_at": "2019-08-24T14:15:22Z",
  • "monthly_fee_date": "string",
  • "reference_id": "string",
  • "user_fields": {
    },
  • "is_refund": true
}

Payments

Fetch a payment by ID

path Parameters
id
required
string
header Parameters
x-account-id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "entity": "payment",
  • "status": "processing",
  • "billing_details": {
    },
  • "amount": 9007199254740991,
  • "amount_authorized": 9007199254740991,
  • "amount_captured": 9007199254740991,
  • "amount_refunded": 9007199254740991,
  • "amount_voided": 9007199254740991,
  • "amount_disputed": 9007199254740991,
  • "amount_reversed": 9007199254740991,
  • "amount_rejected": 9007199254740991,
  • "cvv": "M",
  • "avs": "A",
  • "address_line1_check": "pass",
  • "address_postal_code_check": "pass",
  • "cvv_check": "pass",
  • "signature": {
    },
  • "return_code": "string",
  • "return_message": "string",
  • "failure_code": "string",
  • "failure_message": "string",
  • "cancelled_at": "2019-08-24T14:15:22Z",
  • "cancel_reason": "string",
  • "decline_category": "string",
  • "decline_category_text": "string",
  • "emv_tag_data": "string",
  • "entry_mode": "keyed",
  • "reversed": true,
  • "reversal_id": "string",
  • "reversal_expected": true,
  • "disputed": true,
  • "dispute_id": "string",
  • "order_details": {
    },
  • "gateway_response": {
    },
  • "payment_intent_id": "string",
  • "payment_method_id": "string",
  • "payment_method": {
    },
  • "auth_code": "string",
  • "auth_response_text": "string",
  • "external": true,
  • "card_present": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "account_id": "string",
  • "reference_id": "string",
  • "user_fields": {
    },
  • "description": "string",
  • "settlement_status": "settled",
  • "settled_at": "string"
}

Accounts

Fetch Partner Processing Plan

Use this endpoint to retrieve the processing plan details for a specific account. Processing plans define fee structures, interchange rates, and payout schedules. This information is essential for understanding your cost structure and ensuring accurate fee calculations for your payment processing.

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "plan_type": "FLAT_RATE",
  • "effective_date": "string",
  • "accepted_cards": [
    ],
  • "auth_fee": {
    },
  • "fees": {
    },
  • "fees_paid_by_partner": {
    },
  • "partner_pays_chargeback_amount": true,
  • "comment": "string",
  • "interchange_cost": "GROSS",
  • "bank_processing_plan_settings": {
    }
}