Payment

Get access token using client credentials #

Request Body schema: application/json #

Token request parameters

grant_typerequired	string Value:”client_credentials”Must be “client_credentials”
client_idrequired	stringAccess key ID
client_secretrequired	stringAccess key secret
scoperequired	stringThe access key scope

Responses #

200 A successful access token response as per RFC6749

Response Schema: application/json #

access_tokenrequired	string
token_typerequired	string
expires_inrequired	number

400 An unsuccessful access token response as per RFC6749

Response Schema: application/json #

errorrequired

string Enum:”invalid_request””invalid_client””invalid_grant””unauthorized_client””unsupported_grant_type””invalid_scope”

#

Request a payment or payout #

Send a payment or payout. Successful payout requests will always return a 202 response.

Authorizations:

bearer

#

HTTP: bearer #

HTTP Authorization Scheme: bearer

Bearer format: JWT

header Parameters #

Cko-Idempotency-Key	stringAn optional idempotency key for safely retrying payment requests.
Authorizationrequired	string

Request Body schema: application/json #

Request a payment or payout.

Tabs:

• Payment: Standard payment request.
• Payment Context: Use a payment context ID, etc.
• Card Payout: Card payout request.
• Bank Payout: Bank payout request.

One of #

PaymentRequestDto

currencyrequired

string = 3 characters The three-letter ISO currency code (required, 3 characters).

Source required – object – The source of the payment (e.g., card, bank, etc).

typerequired	stringType of payment source
number	string
expiry_month	number
expiry_year	number
cvv	string

amount	number >= 0 The payment amount in the minor currency unit (e.g., cents). Omit or set to 0 to perform a card verification.
payment_type	string Default: “Regular” Enum:”Regular””Recurring””MOTO””Installment””PayLater””Unscheduled”The type of payment. Required for cardholder-not-present payments (e.g., mail/phone orders, MITs). For MITs, must NOT be “Regular”. Enum: “Regular”, “Recurring”, “MOTO”, “Installment”, “PayLater”, “Unscheduled”.
reference	string <= 80 characters A reference to identify the payment (e.g., order number). Max 80 chars. See Payfac docs for per-scheme limits.
description	string <= 100 characters A description of the payment (max 100 characters).
authorization_type	string Default: “Final” Enum:”Final””Estimated”The authorization type. Enum: “Final”, “Estimated”.
capture	boolean Default: trueWhether to capture the payment (if applicable). Default: true.
capture_on	string <date-time> A timestamp (ISO 8601) for scheduled capture. Providing this sets capture to true.
merchant_initiated	booleanFlags the payment as a merchant-initiated transaction (MIT). Must be true for all MITs. If true, payment_type must not be “Regular”.

Responses #

201 Payment processed successfully

Response Schema: application/json #

id	string
status	string
approved	boolean

202 Payment asynchronous or further action required

Response Schema: application/json #

id	string
status	string
approved	boolean

401 Unauthorized

422 Invalid data was sent

Response Schema: application/json #

request_idrequired	stringThe unique request identifier.
error_typerequired	stringThe error type.
error_codesrequired	Array of stringsThe error codes.

429 Too many requests or duplicate request detected
502 Bad gateway

Get payment details #

Returns the details of the payment with the specified identifier string.

Authorizations:

bearerbearer

#

HTTP: bearer #

HTTP Authorization Scheme: bearer

Bearer format: JWT

path Parameters #

idrequired

string^(pay|sid)_(\w{26})$The payment or payment session identifier

header Parameters #

Authorizationrequired

string

Responses #

200 Payment retrieved successfully
Response Schema: application/json

One of #

Object

idrequired	stringPayment unique identifier
requested_onrequired	string <date-time> The date/time the payment was requested
amountrequired	integerThe original payment amount
currencyrequired	stringThe three-letter ISO currency code of the payment
statusrequired	string Enum:”Pending””Authorized””Card Verified””Voided””Partially Captured””Captured””Partially Refunded””Refunded””Declined””Canceled””Expired””Paid””Retry Scheduled”The status of the payment
approvedrequired	booleanWhether the payment was successful
_linksrequired	object >= 2 properties The links related to the payment
source	objectThe source of the payment
destination	objectThe destination of the payment
amount_requested	integer or nullThe full amount from the original authorization, if a partial authorization was requested.
payment_type	string or null Default: “Regular” Enum:”Regular””Recurring””MOTO””Installment””PayLater””Unscheduled”The payment type
payment_plan	object or nullThe details of a recurring subscription or installment
reference	string or nullYour reference for the payment
description	string or nullA description of the payment
expires_on	string or nullThe timestamp for when the authorization’s validity period expires
balances	object or nullThe payment balances
3ds	object or null3D Secure payment processing info
authentication	object or nullAuthentication info
risk	object or nullRisk assessment results
customer	object or nullThe customer to which this payment is linked
billing_descriptor	object or nullBilling descriptor
shipping	object or nullShipping details
payment_ip	string or nullThe IP address used to make the payment
sender	object or nullSender information
amount_allocations	Array of objects or nullThe sub-entities that the payment is being processed on behalf of
recipient	object or nullRecipient information
processing	object or nullProcessing data
items	Array of objects or nullOrder line items

metadata

object or null Additional metadata

property name*additional property any

eci	string or nullECI security level
scheme_id	string or nullScheme transaction identifier
actions	Array of objects or nullSummary of the payment’s actions
retry	object or nullAsync retry config
pan_type_processed	string or null Enum:”fpan””dpan”Type of PAN used for the payment
cko_network_token_available	boolean or nullIf Checkout Network Token was available
instruction	object or nullPayment instruction details

Object

idrequired	stringPayout unique identifier
requested_onrequired	string <date-time> The date/time the payout was requested
sourcerequired	objectThe source of the payout
destinationrequired	objectThe destination of the payout
amountrequired	integerThe original payout amount
currencyrequired	stringThe three-letter ISO currency code of the payout
reference	string or nullYour reference for the payout
billing_descriptor	object or nullDetails about the billing descriptor
statusrequired	string Enum:”Pending””Paid””Declined””Returned”The status of the payout
approvedrequired	booleanWhether the authorization was successful
sender	object or nullInformation about the sender of the payment’s funds
instruction	object or nullDetails about the instruction for payouts to bank accounts
_linksrequired	object non-empty Links related to the payouts

Object

idrequired	stringThe unique identifier for the payout.
requested_onrequired	string <date-time> The UTC date and time the payout was requested.
processed_onrequired	string or null <date-time> The UTC date and time the payout was approved or declined.
sourcerequired	objectThe source of the payout.
destinationrequired	objectThe payout destination.
amountrequired	integerThe amount to be paid out to the recipient.
currencyrequired	stringThe destination currency, as a three-letter ISO 4217 code.
statusrequired	string Enum:”pending””approved””declined”The status of the payout.
linksrequired	objectThe links related to the payment.
reference	string or null <= 50 characters An internal reference to identify the payout.
billing_descriptor	object or nullDetails about the billing descriptor.
sender	object or nullDetails about the payout sender.
scheme_id	string or nullThe scheme transaction identifier.
instruction	object or nullDetails about the instruction for the payout.

metadata

object or null A set of key-value pairs to attach to the payment.

property name*additional property any

401 Unauthorized
404 Payment not found

Get payment actions #

Returns all the actions associated with a payment ordered by processing date in descending order (latest first).

Authorizations

bearerbearer

path Parameters #

idrequired

string^(pay)_(\w{26})$The payment identifier

header Parameters #

Authorizationrequired

string

Responses #

200 Payment actions retrieved successfully

Cko-Request-Id	stringThe unique identifier of the request
Cko-Version	stringThe version of the API

Response Schema: application/json #

One of

PaymentActionDto

Array

idrequired	string
typerequired	string Enum:”Authorization””Card Verification””Void””Capture””Refund””Payout””Return”
amountrequired	number
response_coderequired	string
processed_onrequired	string <date-time>
approvedrequired	boolean
auth_code	string
response_summary	string
authorization_type	string Enum:”Final””Estimated””Incremental”
reference	string

amount_allocations

Array

id required	string
amount required	number
reference	string
commission	object

processing	object
items	Array of objects
metadata	object

401 Unauthorized
404 Payment not found

Increment authorization #

Request an incremental authorization to increase the authorization amount or extend the authorization’s validity period.

Authorizations

bearerbearer

#

HTTP: bearer #

HTTP Authorization Scheme: bearer

Bearer format: JWT

path Parameters #

idrequired

string^(pay)_(\w{26})$The payment identifier

header Parameters #

Authorizationrequired	string
Cko-Idempotency-Key	stringAn optional idempotency key for safely retrying payment requests.

Request Body schema: application/json #

Increment authorization request body

amount	number >= 0 The amount to increase the authorization by. Omit or set to 0 to only extend the validity period.
reference	stringA reference you can later use to identify this authorization request.
metadata	objectA set of key-value pairs to attach to the authorization request. Only one level of depth is allowed.

Responses #

201 Authorization processed successfully

Cko-Request-Id	stringThe unique identifier of the request
Cko-Version	stringThe version of the API

Response Schema: application/json #

action_idrequired	stringThe unique identifier for the action performed against this payment
amountrequired	numberThe payment amount
currencyrequired	string = 3 characters The three-letter ISO currency code of the payment
approvedrequired	booleanWhether or not the authorization was successful
statusrequired	string Enum:”Authorized””Declined”The status of the payment
response_coderequired	stringThe Gateway response code
processed_onrequired	string <date-time> The date/time the payment was processed
_linksrequired	objectThe links related to the payment
auth_code	stringThe acquirer authorization code if the payment was authorized
response_summary	stringThe Gateway response summary
expires_on	stringThe timestamp (ISO 8601 code) for when the authorization’s validity period ends
balances	objectThe payment balances
reference	stringYour reference for the payment
processing	objectReturns information related to the processing of the payment
eci	stringThe final Electronic Commerce Indicator (ECI) security level used to authorize the payment
scheme_id	stringThe scheme transaction identifier

401 Unauthorized
403 Incremental authorization not allowed
404 Payment not found

422 Invalid data was sent

Response Schema: application/json #

request_idrequired	stringThe unique request identifier.
error_typerequired	stringThe error type.
error_codesrequired	Array of stringsThe error codes.

502 Bad gateway

Cancel a scheduled retry #

Cancels an upcoming retry, if there is one scheduled. Cancellation requests are processed asynchronously. You can use workflows to be notified if the cancellation is successful.

Authorizations

bearerbearer

#

HTTP: bearer #

HTTP Authorization Scheme: bearer

Bearer format: JWT

path Parameters #

idrequired

string^(pay)_(\w{26})$The unique payment identifier.

header Parameters #

Authorizationrequired	string
Cko-Idempotency-Key	stringAn optional idempotency key for safely retrying payment requests.

Request Body schema: application/json #

Cancel retry request body

reference

string <= 80 characters A reference you can later use to identify this cancellation request (max 80 characters).

Responses #

202 Cancellation accepted

Cko-Request-Id	stringThe unique identifier of the request
Cko-Version	stringThe version of the API

Response Schema: application/json #

action_idrequired	stringThe unique identifier for the cancellation action.
referencerequired	stringYour reference for the cancellation request.
_linksrequired	object >= 2 properties The links related to the cancellation.

401 Unauthorized
403 Cancellation not allowed
404 Payment not found

422 Invalid data sent

Response Schema: application/json #

request_idrequired	stringThe unique request identifier.
error_typerequired	stringThe error type.
error_codesrequired	Array of stringsThe error codes.

502 Bad gateway

Capture a payment #

Captures a payment if supported by the payment method. For card payments, capture requests are processed asynchronously. You can use workflows to be notified if the capture is successful.

Authorizations:

bearerbearer

#

HTTP: bearer #

HTTP Authorization Scheme: bearer

Bearer format: JWT

path Parameters #

idrequired

string^(pay)_(\w{26})$The payment identifier

header Parameters #

Authorizationrequired	string
Cko-Idempotency-Key	stringAn optional idempotency key for safely retrying payment requests.

Request Body schema: application/json #

Capture payment request body

amount	number >= 0 The amount to capture. If not specified, the full payment amount will be captured.
capture_type	string Default: “Final” Enum:”NonFinal””Final”The type of capture. If set to Final, the remaining available-to-capture balance will be voided.
reference	string <= 80 characters A reference you can later use to identify this capture request (max 80 chars, Amex: 30 chars).
customer	objectThe customer’s details. Required if source.type is tamara.
description	string <= 100 characters A description of the payment (max 100 chars).
billing_descriptor	objectBilling descriptor for the capture.
shipping	objectThe shipping details.
items	Array of objectsThe order line items.
amount_allocations	Array of objectsThe sub-entities that the payment is being processed on behalf of.
processing	objectProcessing settings for the capture.
metadata	objectA set of key-value pairs to attach to the capture request. Only one level of depth is allowed.

Responses #

202 Capture accepted

Cko-Request-Id	stringThe unique identifier of the request
Cko-Version	stringThe version of the API

Response Schema: application/json #

action_idrequired	stringThe unique identifier for the capture action.
referencerequired	stringYour reference for the capture request.
_linksrequired	object >= 2 properties The links related to the capture.

401 Unauthorized
403 Capture not allowed
404 Payment not found

422 Invalid data sent

Response Schema: application/json #

request_idrequired	stringThe unique request identifier.
error_typerequired	stringThe error type.
error_codesrequired	Array of stringsThe error codes.

502 Bad gateway

Refund a payment #

Refunds a payment if supported by the payment method. For card payments, refund requests are processed asynchronously. You can use workflows to be notified if the refund is successful.

Authorizations:

bearerbearer

#

HTTP: bearer #

HTTP Authorization Scheme: bearer

Bearer format: JWT

path Parameters #

idrequired

string^(pay)_(\w{26})$The payment identifier

header Parameters #

Authorizationrequired	string
Cko-Idempotency-Key	stringAn optional idempotency key for safely retrying payment requests.

Request Body schema: application/json #

Refund payment request body

site_identifierrequired	stringIdentifies your client site.
timestamprequired	stringThe Unix Epoch time of the call.
versionrequired	stringThe version of the API.
signaturerequired	stringThe HMAC signature for the request.
pnm_payment_identifierrequired	stringThe unique, Payfac-created identifier for this payment.
refund_amount	numberThe amount to be refunded. This parameter should only be included for partial-amount refunds.
refund_currency	stringThe currency for the refund (e.g., USD).

Responses #

202 Refund accepted

Cko-Request-Id	stringThe unique identifier of the request
Cko-Version	stringThe version of the API

Response Schema: application/json #

action_idrequired	stringThe unique identifier for the refund action.
referencerequired	stringYour reference for the refund request.
_linksrequired	object >= 2 properties The links related to the refund.

401 Unauthorized
403 Refund not allowed
404 Payment not found

422 Invalid data sent

Response Schema: application/json #

request_idrequired	stringThe unique request identifier.
error_typerequired	stringThe error type.
error_codesrequired	Array of stringsThe error codes.

502 Bad gateway

Reverse a payment #

Beta

You can reverse a payment to return funds back to the customer, without having to manage the appropriate action to take based on the payment’s status.

Depending on the payment’s current status, requesting a payment reversal will automatically perform one of the following actions:

• Fully refund a captured payment.
• Void an authorized payment.
• Cancel retries on a payment with pending retries.
• Refund partially captured funds and void any remaining authorization amount.
• Refund all captured funds from a partial refund and void any remaining authorization amount.

You can only request a payment reversal for card authorizations, captures, or an authorisation attempt that has a retry scheduled.

You cannot reverse a payment that has already been fully refunded, voided, or cancelled. If you attempt to do so, you’ll receive a 204 – No Content response code.

For card payments, reversal requests are processed asynchronously. You can use workflows to be notified when the reversal action completes. Note that the notification will depend on the reversal action taken; for example, for voided payments you will receive a payment_voided notification, and so on.

The reversal request will be rejected with a 403 – Forbidden response code if the payment cannot be reversed. This may happen if:

• the payment is not a card payment
• the payment is not authorized and is still in the process of 3D Secure (3DS) authentication

Authorizations:

bearerbearer

#

HTTP: bearer #

HTTP Authorization Scheme: bearer

Bearer format: JWT

path Parameters #

idrequired

string^(pay)_(\w{26})$The unique identifier for the payment.

header Parameters #

Authorizationrequired	string
Cko-Idempotency-Key	stringAn optional idempotency key for safely retrying payment requests.

Request Body schema: application/json #

Reverse payment request body

site_identifierrequired	stringIdentifies your client site.
timestamprequired	stringThe Unix Epoch time of the call.
versionrequired	stringThe version of the API.
signaturerequired	stringThe HMAC signature for the request.
pnm_payment_identifierrequired	stringThe unique, Payfac-created identifier for this payment.
agent_identifier	stringThe name or ID of the client agent cancelling the payment.
void_if_not_settled	stringSet this parameter to true to completely cancel a payment that has not been settled.
refund_amount	numberThe amount to be refunded. This parameter should only be included for partial-amount refunds.
refund_currency	stringThe currency for the refund (e.g., USD).

Responses #

202 Reversal accepted

Cko-Request-Id	stringThe unique identifier of the request
Cko-Version	stringThe version of the API

Response Schema: application/json #

action_idrequired	stringThe unique identifier for the payment reversal action.
referencerequired	stringA unique reference for the payment reversal.
_linksrequired	objectLinks related to the payment reversal.

204 Payment has already been reversed
401 Unauthorized
403 Refund not allowed
404 Payment not found

422 Invalid data sent

Response Schema: application/json #

request_idrequired	stringThe unique request identifier.
error_typerequired	stringThe error type.
error_codesrequired	Array of stringsThe error codes.

502 Bad gateway

Void a payment #

Voids a payment if supported by the payment method.

For card payments, void requests are processed asynchronously. You can use workflows to be notified if the void is successful.

Authorizations

bearer or bearer

#

HTTP: bearer #

HTTP Authorization Scheme: bearer

Bearer format: JWT

path Parameters #

idrequired

string^(pay)_(\w{26})$The payment identifier

header Parameters #

Authorizationrequired	string
Cko-Idempotency-Key	stringAn optional idempotency key for safely retrying payment requests.

Request Body schema: application/json #

Void payment request body

reference	string <= 80 characters A reference you can later use to identify this void request (max 80 chars, Amex: 30 chars).
metadata	objectA set of key-value pairs to attach to the void request. Only one level of depth is allowed.

Responses #

202 Void accepted

Cko-Request-Id	stringThe unique identifier of the request
Cko-Version	stringThe version of the API

Response Schema: application/json #

action_idrequired	stringThe unique identifier for the void action.
referencerequired	stringYour reference for the void request.
_linksrequired	object >= 2 properties The links related to the void.

401 Unauthorized
403 Void not allowed
404 Payment not found

422 Invalid data sent

Response Schema: application/json #

request_idrequired	stringThe unique request identifier.
error_typerequired	stringThe error type.
error_codesrequired	Array of stringsThe error codes.

502 Bad gateway

Search payments #

Beta

Search and filter through your payment data to retrieve payments that match your query.

If a search returns more results than the value specified in limit, additional results are returned in a new page. A link to the next page of results is returned in the response’s _links.next.href field.

For more information on search syntax, see the Search and filter payments documentation.

Authorizations:

bearer or bearer

#

HTTP: bearer #

HTTP Authorization Scheme: bearer

Bearer format: JWT

header Parameters #

Authorizationrequired

string

Request Body schema: application/json #

Search payments request body

queryrequired	string <= 1024 characters The query string.
limit	number [ 1 .. 1000 ] Default: 10The number of results to return per page.
from	stringThe UTC date and time for the query start in ISO 8601 format. Required if “to” is provided.
to	stringThe UTC date and time for the query end in ISO 8601 format. Required if “from” is provided.

Responses #

202 Successful search

Response Schema: application/json

One of

Object

Array

idrequired	stringThe unique identifier of the payment.
requested_onrequired	stringThe UTC date and time the payment was requested, in ISO 8601 format.
sourcerequired	objectThe source of the payment.
amountrequired	numberThe original payment amount.
amount_requested	numberThe full amount from the original authorization, if a partial authorization was requested.
currencyrequired	stringThe currency of the payment, as a three-letter ISO currency code.
payment_type	stringThe type of payment.
processing_channel_id	stringThe unique identifier of the processing channel that was used for the payment.
reference	stringThe reference for the payment.
statusrequired	stringThe status of the payment.
balances	objectThe payment’s balances.
3ds	objectDetails relating to payments processed with 3D Secure (3DS).
risk	objectThe payment’s risk assessment results.
customer	objectThe customer linked to the payment.
billing_descriptor	objectAn optional description displayed on the customer’s statement identifying a purchase.
metadata	objectA set of key-value pairs attached to the payout, used to store additional information.
actions	Array of objectsThe actions for the payment.

Object

Array

idrequired	stringThe unique identifier of the payout.
requested_onrequired	stringThe UTC date and time the payment was requested, in ISO 8601 format.
destinationrequired	objectThe destination of the payout.
amountrequired	numberThe original payout amount.
currencyrequired	stringThe currency of the payout, as a three-letter ISO currency code.
reference	stringThe reference for the payout.
billing_descriptor	objectThe billing descriptor details.
statusrequired	stringThe status of the payout.
processing_channel_id	stringThe unique identifier of the processing channel that was used for the payout.
sender	objectThe payout sender’s details.
actions	Array of objectsThe actions for the payout.

Object

Array

idrequired	stringThe unique identifier of the payout.
requested_onrequired	stringThe UTC date and time the payment was requested, in ISO 8601 format.
destinationrequired	objectThe destination of the payout.
amountrequired	numberThe original payout amount.
currencyrequired	stringThe currency of the payout, as a three-letter ISO currency code.
reference	stringThe reference for the payout.
billing_descriptor	objectThe billing descriptor details.
statusrequired	stringThe status of the payout.
processing_channel_id	stringThe unique identifier of the processing channel that was used for the payout.
sender	objectThe payout sender’s details.
metadata	objectA set of key-value pairs attached to the payout, used to store additional information.
actions	Array of objectsThe actions for the payout.

400 Invalid input

Response Schema: application/json #

request_idrequired	stringThe unique request identifier.
error_typerequired	stringThe error type.
error_codesrequired	Array of stringsThe error codes.

401 Unauthorized
403 Forbidden

422 Invalid data sent

Response Schema: application/json #

request_idrequired	stringThe unique request identifier.
error_typerequired	stringThe error type.
error_codesrequired	Array of stringsThe error codes.

#

Get payment lists #

Returns a list of your business’ payments that match the specified reference. Results are returned in reverse chronological order, with the most recent payments shown first.

Authorizations

bearer or bearer

#

HTTP: bearer #

HTTP Authorization Scheme: bearer

Bearer format: JWT

query Parameters #

referencerequired	stringA reference, such as an order ID, that can be used to identify the payment
limit	number [ 1 .. 100 ] Default: 10 Example: limit=10The numbers of results to retrieve
skip	number >= 0 Default: 0 Example: skip=0The number of results to skip

header Parameters #

Authorizationrequired

string

202 Payments retrieved successfully
401 Unauthorized
422 Unprocessable paging