Create payment

Browse API reference

POST/paymentspayment

Use this method to run a sale or a pre-authorization with a customer's payment card.

In the response, our gateway returns information about the card payment and a paymentId, which you need for the following methods:

Retrieve payment - View the details of the card payment.
Adjust payment - Update the details of the card payment.
Capture payment - Capture the pre-authorization.
Reverse payment - Cancel the card payment if it's in an open batch.
Refund payment - Run a referenced refund to return funds to the payment card.

Payment methods

Cards - Credit, debit, and EBT
Digital wallets - Apple Pay® and Google Pay®
Tokens - Secure tokens and single-use tokens

Features

Our Create Payment method also supports the following features:

Repeat payments - Run multiple payments as part of a payment schedule that you manage with your own software.
Offline sales - Run a sale or a pre-authorization if the terminal loses its connection to our gateway.
Tokenization - Save card details to use in future transactions.
3-D Secure - Verify the identity of the cardholder.
Custom fields - Add your own data to a payment.
Tips - Add tips to the card payment.
Taxes - Add local taxes to the card payment.
Surcharging - Add a surcharge to the card payment.
Dual pricing - Offer different prices based on payment method, for example, if you use our RewardPay Choice pricing program.
Healthcare - Accept payments from Health Savings Accounts (HSA) and Flexible Spending Accounts (FSA).

Parameters

Name	In	Type	Description
`Idempotency-Key`Required	header	`string`	Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. For more information about the idempotency key, go to Idempotency.

Request body

application/json · required

Field Edit request inputs →

autoCaptureboolean
Indicates if we should automatically capture the payment amount. true Run a sale and automatically capture the transaction. false Run a pre-authorization and capture the transaction later. Note: If you send false and the terminal doesn't support pre-authorization, we set the transaction's status to pending. The merchant must capture the transaction to take payment from the customer.
channelstringrequired
Channel that the merchant used to receive the payment details.poswebmoto
credentialOnFileobject
Object that contains information about saving the customer’s payment details.
- externalVaultboolean
  Indicates if the merchant uses a third-party vault to store the customer’s payment details.
- mitAgreementstring
  Indicates how the merchant can use the customer's card details to run future card transactions, as agreed with the customer. If you send a value for the mitAgreement parameter, you must also include the standingInstructions object in your request. unscheduled Transactions for a fixed or variable amount that the merchant runs at a certain predefined event. recurring Transactions for a fixed amount that the merchant runs at regular intervals, for example, monthly. Recurring transactions don’t have a fixed duration and run until the customer cancels the agreement. installment Transactions for a fixed amount that the merchant runs at regular intervals, for example, monthly. Installment transactions have a fixed duration. Note: If you send a value for mitAgreement, you must send the standingInstructions object in the paymentOrder object.unscheduledrecurringinstallment
- secureTokenIdstring
  Unique identifier that the merchant creates for the secure token that represents the customer’s payment details. Note: If you do not send a value for the secureTokenId parameter, our gateway generates a unique identifier for the token.0–200 chars
- tokenizeboolean
  Indicates if our gateway should tokenize the customer’s payment details as part of the transaction.
customFieldsobject[]
Array of customField objects.
- namestringrequired
  Name of the custom field.1–56 chars
- valuestringrequired
  Value for the custom field.1–100 chars
customerobject
Object that contains the customer's contact details and address information. Contains parameters required for Level 2, Level 3, and CEDP transactions.
- billingAddressobject
  Object that contains information about the address.
  - address1stringrequired
    Address line 1.≤ 150 chars
  - address2string
    Address line 2.≤ 150 chars
  - address3string
    Address line 3.≤ 150 chars
  - citystringrequired
    City.≤ 50 chars
  - countrystringrequired
    Two-digit country code for the country that the business operates in. The format follows the ISO-3166-1 standard.2–2 chars
  - postalCodestringrequired
    Zip code or postal code.≤ 10 chars
  - statestringrequired
    Name of the state or state abbreviation.≤ 50 chars
- contactMethodsobject[]
  Array of polymorphic objects, which contain contact information. The value of the type parameter determines which variant you should use: email Email address phone Phone number mobile Mobile number fax Fax number
  - emailobject
    +2 more fields at deeper levels — see the full spec
  - phoneobject
    +2 more fields at deeper levels — see the full spec
  - mobileobject
    +2 more fields at deeper levels — see the full spec
  - faxobject
    +2 more fields at deeper levels — see the full spec
- dateOfBirthstringdate
  Customer's date of birth. The format for this value is YYYY-MM-DD.
- firstNamestring
  Customer's first name.0–60 chars
- lastNamestring
  Customer's last name.0–60 chars
- notificationLanguagestringiso-639-1
  Language that the customer uses for notifications. This code follows the ISO 639-1 alpha-2 standard.2–2 charsenfr
- referenceNumberstring
  Identifier of the transaction, also known as a customer code. For requests, you must send a value for referenceNumber if the customer provides one. Required for Level 2, Level 3, and CEDP transactions.0–48 chars
- shippingAddressobject
  Object that contains information about the customer and their shipping address. Contains parameters required for Level 3 and CEDP transactions.
  - addressobject
    Object that contains information about the address.+7 more fields at deeper levels — see the full spec
  - recipientNamestring
    Recipient's name. Required for Level 3 and CEDP transactions.0–50 chars
ipAddressobject
Object that contains the IP address of the device that sent the request.
- typestringrequired
  Internet protocol version of the IP address.ipv4ipv6
- valuestringrequired
  IP address of the device.
offlineProcessingobject
Object that contains information about the transaction if the merchant ran it when the terminal was offline.
- approvalCodestring
  Approval code for the transaction from the processor.0–48 chars
- dateTimestringdate-time
  Date and time that the merchant ran the transaction. The date follows the ISO 8601 standard.
- operationstringrequired
  Status of the transaction.offlineDeclineofflineApprovaldeferredAuthorization
operatorstring
Operator who ran the transaction.0–50 chars
orderobjectrequired
Object that contains information about the payment.
- acceptPartialAmountboolean
  Indicates if the merchant accepts a partial authorization for this payment. The value is one of the following: true If the cardholder doesn't have the full amount available in their account, our gateway processes a partial payment. false If the cardholder doesn't have the full amount available in their account, our gateway declines the payment.
- breakdownobject
  Object that contains information about the breakdown of the transaction. Contains parameters required for Level 2, Level 3, and CEDP transactions.
  - dutyAmountintegerint64
    Amount of duties or fees that apply to the order. The value is in the currency's lowest denomination, for example, cents. Required for Level 3 and CEDP transactions.
  - freightAmountintegerint64
    Amount for shipping in the currency's lowest denomination, for example, cents. Required for Level 3 and CEDP transactions.
  - itemsobject[]
    Array of objects that contain information about each item that the customer purchased. Contains parameters required for Level 3 and CEDP transactions.+16 more fields at deeper levels — see the full spec
  - cashbackAmountintegerint64
    Amount of cashback for the transaction.
  - dualPricingobject
    Object that contains information about dual pricing.+2 more fields at deeper levels — see the full spec
  - healthcareExpensesobject[]
    Array of healthcareExpense objects that contain information about healthcare expenses.+2 more fields at deeper levels — see the full spec
  - subtotalintegerint64required
    Amount of the transaction before tax and fees. The value is in the currency’s lowest denomination, for example, cents. Required for Level 2, Level 3, and CEDP transactions.
  - surchargeobject
    Object that contains information about the surcharge.+1 more fields at deeper levels — see the full spec
  - tipobject
    Object that contains information about the tip.+3 more fields at deeper levels — see the full spec
  - taxesobject[]
    Array of polymorphic tax objects, which contain information about a tax. The value of the type parameter determines which variant you should use: amount Tax is a fixed amount. rate Tax is a percentage. Required for Level 2, Level 3, and CEDP transactions.+8 more fields at deeper levels — see the full spec
- amountintegerint64required
  Total amount of the transaction. The value is in the currency’s lowest denomination, for example, cents.
- currencystringrequired
  Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
- descriptionstring
  Description of the transaction.0–1024 chars
- orderIdstringrequired
  Unique identifier that the merchant assigns to the transaction.1–24 chars
- dccOfferobject
  Object that contains information about the dynamic currency conversion (DCC) offer. For more information about DCC, go to Dynamic Currency Conversion.
  - acceptedboolean
    Indicates if the cardholder accepted DCC offer.
  - fxAmountintegerint64required
    Amount in the cardholder’s currency in the currency’s lowest denomination, for example, cents.
  - fxCurrencystringrequired
    Currency of the transaction in the card’s currency. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
  - fxRatenumberdoublerequired
    Foreign exchange rate for the card's currency.
  - markupnumberdoublerequired
    Markup percentage rate that the DCC provider applies to the foreign exchange rate.
  - offerReferencestring
    Unique identifier of the DCC offer.
- standingInstructionsobject
  Object that contains information about repeat payments. Include this object if the payment is part of a recurring billing schedule and you don't use our subscriptions feature.
  - processingModelstringrequired
    Indicates the type of payment schedule. 'unscheduled' – The payment is not part of a regular billing cycle. 'recurring' – The payment is part of a regular billing cycle with no end date. 'installment' – The payment is part of a regular billing cycle with an end date.unscheduledrecurringinstallment
  - referenceDataOfFirstTxnobject
    Object that contains information about the first payment.+2 more fields at deeper levels — see the full spec
  - sequencestringrequired
    Indicates if this payment is the first payment or if it is a subsequent payment.firstsubsequent
paymentMethodobjectrequired
Polymorphic object that contains payment details. The value of the type parameter determines which variant you should use: card Payment card details secureToken Secure token details digitalWallet Digital wallet details singleUseToken Single-use token details
- cardobject
  Object that contains information about the customer’s payment card.
  - accountTypestring
    Indicates the customer’s account type. Note: Send a value for accountType only for bank account details.checkingsavings
  - cardDetailsobjectrequired
    Polymorphic object that contains payment card information. The value of the entryMethod parameter determines which variant you should use: raw Unencrypted payment data directly from the device. icc Payment data that the device captured from the chip. keyed Payment data that the merchant entered manually. swiped Payment data that the device captured from the magnetic strip.+132 more fields at deeper levels — see the full spec
  - typestringrequired
    Method that the terminal used to take the payment.card
- secureTokenobject
  Object that contains information about the secure token that represents the customer’s payment details.
  - accountTypestring
    Indicates the customer’s account type. Note: Send a value for accountType only if the secure token represents bank account details.checkingsavings
  - secCodestring
    Indicates how the customer authorized the ACH transaction. Send one of the following values: web – Online transaction. tel – Telephone transaction. ccd – Corporate credit or debit entry for a business bank account. ppd – Pre-arranged transaction. Note: This field is mandatory when the secure token represents ACH bank account details.webtelccdppd
  - tokenstringrequired
    Unique token that the gateway assigned to the payment details.12–19 chars
  - typestringrequired
    Method that the terminal used to take the payment.secureToken
- digitalWalletobject
  Object that contains information about the payment details in the customer’s digital wallet.
  - accountTypestring
    Indicates the customer’s account type. Note: Send a value for accountType only for bank account details.checkingsavings
  - cardholderNamestring
    Cardholder’s name.0–50 chars
  - encryptedDatastringrequired
    Encrypted data of the digital wallet.128–20480 chars
  - serviceProviderstringrequired
    Provider of the digital wallet. Send one of the following values: apple For more information about how to integrate with Apple Pay, go to Apple Pay®. google For more information about how to integrate with google Pay, go to Google Pay®.applegoogle
  - typestringrequired
    Method that the terminal used to take the payment.digitalWallet
- singleUseTokenobject
  Object that contains information about the single-use token, which represents the customer’s payment details.
  - accountTypestring
    Indicates the customer’s account type. Note: Send a value for accountType only if the single-use token represents bank account details.checkingsavings
  - ebtDetailsobject
    Object that contains information about the Electronic Benefit Transfer (EBT) transaction.+5 more fields at deeper levels — see the full spec
  - pinDetailsobject
    Polymorphic object that contains information about a customer's PIN. The value of the dataFormat parameter determines which variant you should use: dukpt PIN information is encrypted. raw PIN information is unencrypted.+7 more fields at deeper levels — see the full spec
  - secCodestring
    Indicates how the customer authorized the ACH transaction. Send one of the following values: web – Online transaction. tel – Telephone transaction. ccd – Corporate credit or debit entry for a business bank account. ppd – Pre-arranged transaction. Note: This field is mandatory when the single-use token represents ACH bank account details.webtelccdppd
  - tokenstringrequired
    Unique token that the gateway assigned to the payment details.128–128 chars
  - typestringrequired
    Method that the terminal used to take the payment.singleUseToken
processAsSaleboolean
Indicates if we should immediately settle the sale transaction. The merchant cannot adjust the transaction if we immediately settle it. Note: If the value for processAsSale is true, the gateway ignores the value in autoCapture.
processingTerminalIdstringrequired
Unique identifier that we assigned to the terminal.4–50 chars
threeDSecureobject
Polymorphic object that contains authentication information from 3-D Secure. The value of the serviceProvider parameter determines which variant you should use: gateway Use our gateway to run a 3-D Secure check. thirdParty Use a third party to run a 3-D Secure check.
- gatewayobject
  Object that contains the 3-D Secure information from our gateway.
  - mpiReferencestringrequired
    Reference that our gateway assigned to the 3-D Secure authentication response.20–20 chars
  - serviceProviderstringrequired
    Provider of your 3-D Secure protocol.gateway
- thirdPartyobject
  Object that contains the 3-D Secure information from a third party.
  - cavvstring
    Cardholder Authentication Verification Value (CAVV) that the card issuer provided to prove that they authorized the online payment.0–50 chars
  - dsTransactionIdstring
    Directory Server Transaction ID that the processor assigned to the request.0–36 chars
  - ecistringrequired
    E-commerce indicator (ECI) result of a the 3-D Secure check.fullyAuthenticatedauthAttempted
  - serviceProviderstringrequired
    Provider of your 3-D Secure protocol.thirdParty
  - xidstring
    Unique transaction identifier that the merchant assigned to the transaction and sent in the authentication request.0–50 chars

Responses

Successful request. We processed the transaction.

201 Created · application/json

{
  "card": {
    "cardNumber": "500165******0000",
    "entryMethod": "keyed",
    "expiryDate": "0328",
    "securityChecks": {
      "avsResult": "U"
    },
    "type": "MasterCard"
  },
  "operator": "Jane",
  "order": {
    "amount": 4999,
    "currency": "USD",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Card Transaction (APPLE)",
    "orderId": "1234567890W"
  },
  "paymentId": "J9VULKIKFP",
  "processingTerminalId": "1234001",
  "supportedOperations": [
    "capture",
    "fullyReverse",
    "partiallyReverse",
    "incrementAuthorization",
    "adjustTip",
    "setAsPending"
  ],
  "transactionResult": {
    "approvalCode": "OK3",
    "authorizedAmount": 4999,
    "currency": "USD",
    "processorResponseCode": "00",
    "responseCode": "A",
    "responseMessage": "APPROVAL",
    "status": "ready",
    "type": "sale"
  }
}

Response schema · 110 of 160 fields

cardobjectrequired
Object that contains the details of the payment card.
- balancesobject[]
  Array of cardBalance objects. Our gateway returns this array only when the customer uses an Electronic Benefit Transfer (EBT) card.
  - amountintegerint64required
    Current balance of the account. This value is in the currency's lowest denomination, for example, cents.
  - benefitCategorystringrequired
    Indicates if the balance relates to an EBT Cash account or EBT SNAP account. cash – EBT Cash foodStamp – EBT SNAPcashfoodStamp
  - currencystringrequired
    Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
- cardNumberstringrequired
  Card number. In the response, our gateway shows only the first six digits and the last four digits of the card number, for example, 500165******0000.12–19 chars
- cardholderNamestring
  Cardholder’s name.1–50 chars
- cardholderSignaturestring
  Cardholder’s signature.
- emvTagsobject[]
  Array of emvTag objects.
  - hexstringrequired
    Hex code of the EMV tag.
  - valuestringrequired
    Value of the EMV tag.
- entryMethodstringrequired
  Method that the device used to capture the card details.icckeyedswipedswipedFallbackcontactlessIcccontactlessMsr
- expiryDatestringrequired
  Expiry date of the customer's card. The format is in MMYY.[0-9]{4}
- secureTokenobject
  Object that contains information about the secure token.
  - customerNamestringrequired
    Customer's name.1–50 chars
  - linkobject
    Object that contains HATEOAS links for the resource.+3 more fields at deeper levels — see the full spec
  - secureTokenIdstringrequired
    Unique identifier that the merchant assigned to the secure token.1–200 chars
  - statusstringrequired
    Status of the customer's bank account. The processor performs a security check on the customer's bank account and returns the status of the account. Note: Depending on the merchant's account settings, this feature may be unavailable.notValidatedcvvValidatedvalidationFailedissueNumberValidatedcardNumberValidatedbankAccountValidated
  - tokenstringrequired
    Token that the merchant can use in future transactions to represent the customer's payment details. The token: Begins with the six-digit identification number 296753. Contains up to 12 digits. Contains a single check digit that we calculate using the Luhn algorithm.12–19 chars
- securityChecksobject
  Object that contains information about card verification and security checks.
  - avsResultstring
    Indicates if the address that the customer provided in the request matches the address linked to the card. Y – The address in the request matches the address linked to the card. N – The address in the request doesn’t match the address linked to the card. A – The street address matches, but ZIP code or postal code doesn’t match. Z The ZIP code or postal code matches, but street address doesn’t match. U – The address information is unavailable. G – The issuer or card brand doesn’t support the Address Verification Service (AVS). R – The AVS is currently unavailable. Try again later. S – There was no AVS data in the request, or it was sent in the wrong format. F For UK addresses, the address in the request matches the address linked to the card. W – For US addresses, the nine-digit ZIP code or postal code in the request matches the address linked to the card but the street address doesn’t. X – For US addresses, the nine-digit ZIP code or postal code and the street address matches the address linked to the card. Note: Our gateway doesn’t automatically decline transactions when the address doesn’t match the address linked to the card, unless the merchant selects this setting in their account.YAZNURGS+3 more
  - cvvResultstring
    Indicates if the card verification value (CVV) that the customer provided in the request matches the CVV on the card. M – The CVV matches the card’s CVV. N – The CVV doesn’t match the card’s CVV. P – The CVV wasn’t processed. U – The CVV isn’t registered. Note: Our gateway doesn’t automatically decline transactions when the CVV doesn’t match the card’s CVV, unless the merchant selects this setting in their account.MNPU
- typestringrequired
  Card brand of the card, for example, Visa.
customFieldsobject[]
Array of customField objects.
- namestringrequired
  Name of the custom field.1–56 chars
- valuestringrequired
  Value for the custom field.1–100 chars
customerobject
Object that contains the customer's contact details and address information.
- billingAddressobject
  Object that contains information about the address.
  - address1string
    Address line 1.≤ 150 chars
  - address2string
    Address line 2.≤ 150 chars
  - address3string
    Address line 3.≤ 150 chars
  - citystring
    City.≤ 50 chars
  - countrystring
    Two-digit country code for the country that the business operates in. The format follows the ISO-3166-1 standard.2–2 chars
  - postalCodestring
    Zip code or postal code.≤ 10 chars
  - statestring
    Name of the state or state abbreviation.≤ 50 chars
- contactMethodsobject[]
  Array of polymorphic objects, which contain contact information. The value of the type parameter determines which variant you should use: email Email address phone Phone number mobile Mobile number fax Fax number
  - emailobject
    +2 more fields at deeper levels — see the full spec
  - phoneobject
    +2 more fields at deeper levels — see the full spec
  - mobileobject
    +2 more fields at deeper levels — see the full spec
  - faxobject
    +2 more fields at deeper levels — see the full spec
- dateOfBirthstringdate
  Customer's date of birth. The format for this value is YYYY-MM-DD.
- firstNamestring
  Customer's first name.0–60 chars
- lastNamestring
  Customer's last name.0–60 chars
- notificationLanguagestringiso-639-1
  Language that the customer uses for notifications. This code follows the ISO 639-1 alpha-2 standard.2–2 charsenfr
- referenceNumberstring
  Identifier of the transaction, also known as a customer code. For requests, you must send a value for referenceNumber if the customer provides one.0–48 chars
- shippingAddressobject
  Object that contains information about the customer and their shipping address.
  - addressobject
    Object that contains information about the address.+7 more fields at deeper levels — see the full spec
  - recipientNamestring
    Recipient's name.0–50 chars
operatorstring
Operator who initiated the request.0–50 chars
orderobjectrequired
Object that contains information about the payment.
- breakdownobject
  Object that contains information about the breakdown of the transaction. Contains parameters required for Level 2, Level 3, and CEDP transactions.
  - convenienceFeeobject
    Object that contains information about the convenience fee for the transaction.+1 more fields at deeper levels — see the full spec
  - dutyAmountintegerint64
    Amount of duties or fees that apply to the order. The value is in the currency's lowest denomination, for example, cents. Required for Level 3 and CEDP transactions.
  - freightAmountintegerint64
    Amount for shipping in the currency's lowest denomination, for example, cents. Required for Level 3 and CEDP transactions.
  - itemsobject[]
    Array of objects that contain information about each item that the customer purchased. Contains parameters required for Level 3 and CEDP transactions.+11 more fields at deeper levels — see the full spec
  - cashbackAmountintegerint64
    Amount of cashback for the transaction.
  - dualPricingobject
    Object that contains information about dual pricing.+6 more fields at deeper levels — see the full spec
  - healthcareExpensesobject[]
    Array of healthcareExpense objects that contain information about healthcare expenses.+2 more fields at deeper levels — see the full spec
  - subtotalintegerint64required
    Amount of the transaction before tax and fees. The value is in the currency’s lowest denomination, for example, cents. Required for Level 2, Level 3, and CEDP transactions.
  - surchargeobject
    Object that contains information about the surcharge.+3 more fields at deeper levels — see the full spec
  - tipobject
    Object that contains information about the tip.+4 more fields at deeper levels — see the full spec
  - taxesobject[]
    List of taxes.+3 more fields at deeper levels — see the full spec
- amountintegerint64required
  Total amount of the transaction. The value is in the currency’s lowest denomination, for example, cents.
- currencystringrequired
  Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
- dateTimestringdate-time
  Date and time that the processor processed the transaction. Our gateway returns this value in the ISO 8601 format.
- descriptionstring
  Description of the transaction.0–1024 chars
- orderIdstringrequired
  Unique identifier that the merchant assigns to the transaction.1–24 chars
- dccOfferobject
  Object that contains information about the dynamic currency conversion (DCC) offer. For more information about DCC, go to Dynamic Currency Conversion.
  - acceptedboolean
    Indicates if the cardholder accepted DCC offer.
  - fxAmountintegerint64required
    Amount in the cardholder’s currency in the currency’s lowest denomination, for example, cents.
  - fxCurrencystringrequired
    Currency of the transaction in the card’s currency. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
  - fxCurrencyCodestring
    Three-digit currency code for the card. This code follows the ISO 4217 standard.3–3 chars
  - fxCurrencyExponentintegerint32
    Number of decimal places between the smallest currency unit and a whole currency unit. For example, for GBP, the smallest currency unit is 1p and it is equal to £0.01. If you use GBP, the value for fxCurrencyExponent is 2.
  - fxRatenumberdoublerequired
    Foreign exchange rate for the card's currency.
  - markupnumberdoublerequired
    Markup percentage rate that the DCC provider applies to the foreign exchange rate.
  - markupTextstring
    Supporting text for the markup rate.
  - offerReferencestring
    Unique identifier of the DCC offer.
  - providerstring
    Name of the DCC provider.
  - sourcestring
    Source that the DCC provider used to get the foreign exchange rates.
- standingInstructionsobject
  Object that contains information about repeat payments. Include this object if the payment is part of a recurring billing schedule and you don't use our subscriptions feature.
  - processingModelstringrequired
    Indicates the type of payment schedule. 'unscheduled' – The payment is not part of a regular billing cycle. 'recurring' – The payment is part of a regular billing cycle with no end date. 'installment' – The payment is part of a regular billing cycle with an end date.unscheduledrecurringinstallment
  - referenceDataOfFirstTxnobject
    Object that contains information about the first payment.+2 more fields at deeper levels — see the full spec
  - sequencestringrequired
    Indicates if this payment is the first payment or if it is a subsequent payment.firstsubsequent
paymentIdstringrequired
Unique identifier that our gateway assigned to the transaction.10–10 chars
processingTerminalIdstringrequired
Unique identifier of the terminal that initiated the transaction.4–50 chars
refundsobject[]
Array of refundSummary objects. Each object contains information about refunds linked to the transaction.
- amountintegerint64required
  Amount of the refund. This value is in the currency’s lowest denomination, for example, cents.
- currencystringrequired
  Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
- dateTimestringdate-timerequired
  Date and time that the refund was processed.
- linkobject
  Object that contains HATEOAS links for the resource.
  - hrefstringrequired
    URL of the target resource.
  - methodstringrequired
    HTTP method that you need to use with the target resource.
  - relstringrequired
    Indicates the relationship between the current resource and the target resource.
- refundIdstringrequired
  Unique identifier of the refund.10–10 chars
- responseCodestringrequired
  Response from the processor. A The processor approved the transaction. D The processor declined the transaction. E The processor received the transaction but will process the transaction later. P The processor authorized a portion of the original amount of the transaction. R The issuer declined the transaction and indicated that the customer should contact their bank. C The issuer declined the transaction and indicated that the merchant should keep the card as it was reported lost or stolen.ADEPRC
- responseMessagestringrequired
  Description of the response from the processor.1–48 chars
- statusstringrequired
  Current status of the refund.readypendingdeclinedcompletereferralpickupreversalreturned+3 more
supportedOperationsstring[]
Array of operations that you can perform on the transaction. Our gateway can return any of the following values: capture Capture the payment. refund Refund the payment. fullyReverse Fully reverse the transaction. partiallyReverse Partially reverse the payment. incrementAuthorization Increase the amount of the authorization. adjustTip Adjust the tip post-payment. addSignature Add a signature to the payment. setAsReady Set the transaction’s status to `ready`. setAsPending Set the transaction’s status to `pending`.
transactionResultobjectrequired
Object that contains information about the transaction response details.
- approvalCodestring
  Authorization code that the processor assigned to the transaction.1–48 chars
- authorizedAmountintegerint64
  Amount that the processor authorized for the transaction. This value is in the currency’s lowest denomination, for example, cents. Notes: For partial authorizations, this amount is lower than the amount in the request. If the value for authorizedAmount is negative, this indicates that the merchant sent funds to the customer.
- cardSchemeReferenceIdstring
  Identifier that the card brand assigns to the payment instruction.1–64 chars
- currencystring
  Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
- ebtTypestring
  Indicates the subtype of EBT in the transaction.cashPurchasecashPurchaseWithCashbackfoodStampPurchasefoodStampVoucherPurchasefoodStampReturnfoodStampVoucherReturncashBalanceInquiryfoodStampBalanceInquiry+1 more
- healthcareIndicatorstring
  Indicates if we processed the payment as a healthcare expense. The value is one of the following: Y We processed the payment as a healthcare expense. N We processed the payment but it didn't contain any healthcare expenses. C We processed the payment but the card isn't linked to a Flexible Spending Account (FSA) or a Health Savings Account (HSA). R We processed the payment but the card doesn't support healthcare expenses.YNCR
- processorResponseCodestring
  Original response code that the processor sent.
- responseCodestringrequired
  Response from the processor. A The processor approved the transaction. D The processor declined the transaction. E The processor received the transaction but will process the transaction later. P The processor authorized a portion of the original amount of the transaction. R The issuer declined the transaction and indicated that the customer should contact their bank. C The issuer declined the transaction and indicated that the merchant should keep the card as it was reported lost or stolen.ADEPRC
- responseMessagestring
  Response description from the processor.1–48 chars
- statusstringrequired
  Status of the transaction. The value is one of the following: ready Successful transaction. We added the payment to the open batch. pending Successful transaction. We added the payment to the open batch, but we don't collect the funds until the merchant captures the transaction. declined Unsuccessful transaction. The cardholder's issuing bank declined the transaction. complete Successful transaction. The funds have moved to the merchant's bank account. referral Unsuccessful transaction. The issuing bank identified an issue with the transaction. You should treat a referral status as a declined transaction. pickup Unsuccessful transaction. The issuing bank has reported that the card is lost or stolen. reversal Transaction canceled. The transaction was canceled, and we removed the transaction from the open batch. admin Transaction under review. We have flagged an issue with the transaction. expired Transaction expired. If a transaction stays in pending status for too long, it expires. accepted Transaction in progress. The transaction is in progress with the processor but we can't confirm the result yet.readypendingdeclinedcompletereferralpickupreversaladmin+2 more
- typestring
  Transaction type.salerefundpreAuthorizationpreAuthorizationCompletion

Validation error

400 Bad Request · application/problem+json

{
  "detail": "'Idempotency-Key' is already in use against a different request",
  "status": 409,
  "title": "Idempotency-Key in use",
  "type": "https://docs.payroc.com/api/errors#idempotency-key-in-use"
}

Response schema · 8 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Identity could not be verified

401 Unauthorized · application/problem+json

{
  "detail": "Your identity could not be verified",
  "status": 401,
  "title": "Not Authorized",
  "type": "https://docs.payroc.com/api/errors#not-authorized"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Do not have permissions to perform this action

403 Forbidden · application/problem+json

{
  "detail": "You do not have the required permissions to perform this action",
  "instance": "https://api.payroc.com/v1/exampleResource/3",
  "resource": "exampleResource",
  "status": 403,
  "title": "Forbidden",
  "type": "https://docs.payroc.com/api/errors#forbidden"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
instancestring
Resource path the action was attempted on
resourcestring
Resource the action was attempted on
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Not acceptable

406 Not Acceptable · application/problem+json

{
  "detail": "Resource does not support the representation requested",
  "status": 406,
  "title": "Not acceptable",
  "type": "https://docs.payroc.com/api/errors#not-acceptable"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Conflict

409 Conflict · application/problem+json

{
  "detail": "The resource you attempted to create already exists",
  "instance": "https://api.payroc.com/v1/merchant/12345",
  "status": 409,
  "title": "Resource already exists",
  "type": "https://docs.payroc.com/api/errors#resource-already-exists"
}

Response schema · 13 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
instancestring
Resource path to the existing resource
linkobject
Object that contains HATEOAS links for the resource.
- hrefstringrequired
  URL of the target resource.
- methodstringrequired
  HTTP method that you need to use with the target resource.
- relstringrequired
  Indicates the relationship between the current resource and the target resource.
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Unsupported media type

415 Unsupported Media Type · application/problem+json

{
  "detail": "You submitted a payload in an unsupported format",
  "status": 415,
  "title": "Unsupported media type",
  "type": "https://docs.payroc.com/api/errors#unsupported-media-type"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

An error has occured

500 Internal Server Error · application/problem+json

{
  "detail": "We are unable to process your request at this time",
  "errors": [
    {
      "message": "Service offline"
    }
  ],
  "status": 500,
  "title": "Api error",
  "type": "https://docs.payroc.com/api/errors#api-error"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- messagestring
  Error message
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Used in workflows

accept-apple-pay accept-google-pay collect-with-hosted-fields pay-with-single-use-token run-a-card-sale run-a-pre-authorization

Create payment

Browse API reference

Parameters

Request body

Responses

Used in workflows

Menu

Sign out

Talk to an engineer