Use this method to create an unreferenced refund. An unreferenced refund is a refund that isn't linked to a payment.
Note: If you have the paymentId of the payment you want to refund, use our Refund Payment method. If you use our Refund Payment method, our gateway sends the refund amount to the customer's original payment method and links the refund to the payment.
In the request, you must provide the customer's payment details and the refund amount.
In the response, our gateway returns information about the refund and a refundId, which you need for the following methods:
Reverse refund - Cancel the refund if it's in an open batch.
Parameters
Name
In
Type
Description
Idempotency-KeyRequired
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.
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
typestringrequired
Type of contact method.email
valuestringrequired
Email address.≤ 50 chars
phoneobject
typestringrequired
Type of contact method.phone
valuestringrequired
Phone number.≤ 15 chars
mobileobject
typestringrequired
Type of contact method.mobile
valuestringrequired
Mobile number.≤ 15 chars
faxobject
typestringrequired
Type of contact method.fax
valuestringrequired
Fax number.≤ 15 chars
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.
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
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.
operatorstring
Operator who initiated the request.0–50 chars
orderobjectrequired
Object that contains information about the refund.
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
descriptionstringrequired
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.
processingTerminalIdstringrequired
Unique identifier that we assigned to the terminal.4–50 chars
refundMethodobjectrequired
Polymorphic object that contains information about the payment method that the merchant uses to refund the customer. The value of the type parameter determines which variant you should use: card Payment card details secureToken Secure 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.
rawobject
Object that contains information about the unencrypted card details.
Object that contains information about the physical device the merchant used to capture the customer’s card details.
categorystring
Indicates if the device is attended or unattended.attendedunattended
configobject
Object that contains information about the configuration of the POS terminal.
quickChipbooleanrequired
Indicates if Quick Chip mode is active on a merchant’s POS terminal.
firmwareVersionstring
Firmware version of the physical device.
modelstringrequired
Model of the device that the merchant used to process the transaction.bbposChpbbposChp2xbbposChp3xbbposRamblerbbposWpbbposWp2bbposWp3genericCtlsMsr+32 more
serialNumberstringrequired
Serial number of the physical device.1–64 chars
downgradeTostring
If an offline transaction is not approved using the initial entry method, reprocess the transaction using a downgraded entry method. For example, an Integrated Circuit Card (ICC) transaction can be downgraded to a swiped transaction or to a keyed transaction.keyedswiped
entryMethodstringrequired
Method that the terminal used to capture the card details.raw
rawDatastringhexadecimalrequired
Unencrypted data from the POS terminal.1–2147483647 chars
iccobject
Object that contains information about the Integrated Circuit Card (ICC).
Object that contains information about the encryption details of the POS terminal.
categorystring
Indicates if the device is attended or unattended.attendedunattended
configobject
Object that contains information about the configuration of the POS terminal.
quickChipbooleanrequired
Indicates if Quick Chip mode is active on a merchant’s POS terminal.
firmwareVersionstring
Firmware version of the physical device.
modelstringrequired
Model of the device that the merchant used to process the transaction.bbposChpbbposChp2xbbposChp3xbbposRamblerbbposWpbbposWp2bbposWp3genericCtlsMsr+32 more
serialNumberstringrequired
Serial number of the physical device.1–64 chars
dataKsnstringhexadecimalrequired
Key serial number.20–20 chars
downgradeTostring
If an offline transaction is not approved using the initial entry method, reprocess the transaction using a downgraded entry method. For example, an Integrated Circuit Card (ICC) transaction can be downgraded to a swiped transaction or a keyed transaction.keyedswiped
ebtDetailsobject
Object that contains information about the Electronic Benefit Transfer (EBT) transaction.
benefitCategorystringrequired
Indicates if the balance relates to an EBT Cash account or an EBT SNAP account. cash – EBT Cash foodStamp – EBT SNAPcashfoodStamp
withdrawalboolean
Indicates whether the customer wants to withdraw cash. Note: Cash withdrawals are available only from EBT Cash accounts.
voucherobject
Object that contains information about the EBT voucher. Note: Vouchers are available only for EBT SNAP payments.
approvalCodestringrequired
Authorization code that the processor issued for the transaction.6–6 chars
serialNumberstringrequired
Serial number of the voucher.7–15 chars
entryMethodstringrequired
Method that the terminal used to capture the card details.icc
firstDigitOfPanstring
First digit of the card number.1–1 chars
iccDatastringhexadecimalrequired
Cardholder data from the ICC. The data consists of EMV tags in Tag-Length-Value (TLV) format.
keyedobject
Object that contains information about the keyed card details.
Object that contains information about the Electronic Benefit Transfer (EBT) transaction.
benefitCategorystringrequired
Indicates if the balance relates to an EBT Cash account or an EBT SNAP account. cash – EBT Cash foodStamp – EBT SNAPcashfoodStamp
withdrawalboolean
Indicates whether the customer wants to withdraw cash. Note: Cash withdrawals are available only from EBT Cash accounts.
voucherobject
Object that contains information about the EBT voucher. Note: Vouchers are available only for EBT SNAP payments.
approvalCodestringrequired
Authorization code that the processor issued for the transaction.6–6 chars
serialNumberstringrequired
Serial number of the voucher.7–15 chars
entryMethodstringrequired
Method that the terminal used to capture the card details.keyed
keyedDataobjectrequired
Polymorphic object that contains payment card details that the merchant manually entered into the device. The value of the dataFormat parameter determines which variant you should use: fullyEncrypted All payment card details are encrypted. partiallyEncrypted Some payment card details are encrypted. plainText Payment card details are in plain text.
fullyEncryptedobject
Object that contains information about the encrypted card data for keyed transactions.
dataFormatstringrequired
Indicates the data format of the customer’s card data. plainText – Data is not truncated and shows the raw data. fullyEncrypted – Data is truncated to show only the first digit of the customer’s account number. partiallyEncrypted – Data is truncated to show only the first six digits and the last four digits of the customer’s card number.fullyEncrypted
deviceobjectrequired
Object that contains information about the encryption details of the POS terminal.
categorystring
Indicates if the device is attended or unattended.attendedunattended
configobject
Object that contains information about the configuration of the POS terminal.
quickChipbooleanrequired
Indicates if Quick Chip mode is active on a merchant’s POS terminal.
firmwareVersionstring
Firmware version of the physical device.
modelstringrequired
Model of the device that the merchant used to process the transaction.bbposChpbbposChp2xbbposChp3xbbposRamblerbbposWpbbposWp2bbposWp3genericCtlsMsr+32 more
serialNumberstringrequired
Serial number of the physical device.1–64 chars
dataKsnstringhexadecimalrequired
Key serial number.20–20 chars
encryptedDatastringhexadecimalrequired
Encrypted card data.1–2147483647 chars
firstDigitOfPanstring
First digit of the customer’s card number.1–1 chars
partiallyEncryptedobject
Object that contains information about the partially-encrypted card data for keyed transactions.
cvvstring
Security code of the customer’s card.[0-9]{3,4}
cvvEncryptedstringhexadecimal
Encrypted security code data.
dataFormatstringrequired
Indicates the data format of the customer’s card data. plainText – Data is not truncated and shows the raw data. fullyEncrypted – Data is truncated to show only the first digit of the customer’s account number. partiallyEncrypted – Data is truncated to show only the first six digits and the last four digits of the customer’s card number.partiallyEncrypted
deviceobjectrequired
Object that contains information about the encryption details of the POS terminal.
categorystring
Indicates if the device is attended or unattended.attendedunattended
configobject
Object that contains information about the configuration of the POS terminal.
quickChipbooleanrequired
Indicates if Quick Chip mode is active on a merchant’s POS terminal.
firmwareVersionstring
Firmware version of the physical device.
modelstringrequired
Model of the device that the merchant used to process the transaction.bbposChpbbposChp2xbbposChp3xbbposRamblerbbposWpbbposWp2bbposWp3genericCtlsMsr+32 more
serialNumberstringrequired
Serial number of the physical device.1–64 chars
dataKsnstringhexadecimalrequired
Key serial number.20–20 chars
encryptedPanstringhexadecimalrequired
Encrypted card number.1–2147483647 chars
expiryDatestringrequired
Expiry date of the customer’s card.[0-9]{4}
issueNumberstring
Issue number of the customer’s card.[0-9]{1,2}
maskedPanstringrequired
Masked card number. The gateway shows only the first six digits and the last four digits of the account number. For example, 453985******7062.12–19 chars
plainTextobject
Object that contains information about the plain-text card data for keyed transactions.
cardNumberstringrequired
Customer’s card number.12–19 chars
cvvstring
Security code of the customer’s card.[0-9]{3,4}
dataFormatstringrequired
Indicates the data format of the customer’s card data. plainText – Data is not truncated and shows the raw data. fullyEncrypted – Data is truncated to show only the first digit of the customer’s account number. partiallyEncrypted – Data is truncated to show only the first six digits and the last four digits of the customer’s card number.plainText
deviceobject
Object that contains information about the physical device the merchant used to capture the customer’s card details.
categorystring
Indicates if the device is attended or unattended.attendedunattended
configobject
Object that contains information about the configuration of the POS terminal.
quickChipbooleanrequired
Indicates if Quick Chip mode is active on a merchant’s POS terminal.
firmwareVersionstring
Firmware version of the physical device.
modelstringrequired
Model of the device that the merchant used to process the transaction.bbposChpbbposChp2xbbposChp3xbbposRamblerbbposWpbbposWp2bbposWp3genericCtlsMsr+32 more
serialNumberstringrequired
Serial number of the physical device.1–64 chars
expiryDatestring
Expiry date of the customer’s card. Note: We require you to send an expiry date for most BIN lookups and electronic voucher transactions.[0-9]{4}
issueNumberstring
Issue number of the customer’s card.[0-9]{1,2}
pinDetailsobject
Polymorphic object that contains information about the customer's PIN.
dukptobject
Object that contains information about encrypted PIN details.
dataFormatstringrequired
Indicates the format of the PIN data.dukpt
pinstringhexadecimalrequired
Encrypted PIN. Note: PIN is encrypted using the DUKPT scheme.1–2147483647 chars
pinKsnstringhexadecimalrequired
Key serial number.20–20 chars
swipedobject
Object that contains information about the customer’s card details for swiped transactions.
If an offline transaction is not approved using the initial entry method, reprocess the transaction using a downgraded entry method. For example, a swiped transaction can be downgraded to a keyed transaction.keyedswiped
ebtDetailsobject
Object that contains information about the Electronic Benefit Transfer (EBT) transaction.
benefitCategorystringrequired
Indicates if the balance relates to an EBT Cash account or an EBT SNAP account. cash – EBT Cash foodStamp – EBT SNAPcashfoodStamp
withdrawalboolean
Indicates whether the customer wants to withdraw cash. Note: Cash withdrawals are available only from EBT Cash accounts.
voucherobject
Object that contains information about the EBT voucher. Note: Vouchers are available only for EBT SNAP payments.
approvalCodestringrequired
Authorization code that the processor issued for the transaction.6–6 chars
serialNumberstringrequired
Serial number of the voucher.7–15 chars
entryMethodstringrequired
Method that the terminal used to capture the card details.swiped
pinDetailsobject
Polymorphic object that contains information about the customer's PIN.
dukptobject
Object that contains information about encrypted PIN details.
dataFormatstringrequired
Indicates the format of the PIN data.dukpt
pinstringhexadecimalrequired
Encrypted PIN. Note: PIN is encrypted using the DUKPT scheme.1–2147483647 chars
pinKsnstringhexadecimalrequired
Key serial number.20–20 chars
swipedDataobjectrequired
Polymorphic object that contains payment card details that a device captured from the magnetic strip. The value of the dataFormat parameter determines which variant you should use: encrypted Payment card details are encrypted. plainText Payment card details are in plain text.
encryptedobject
Object that contains information about the encrypted swiped card data.
dataFormatstringrequired
Format of the card data.encrypted
deviceobjectrequired
Object that contains information about the encryption details of the POS terminal.
categorystring
Indicates if the device is attended or unattended.attendedunattended
configobject
Object that contains information about the configuration of the POS terminal.
quickChipbooleanrequired
Indicates if Quick Chip mode is active on a merchant’s POS terminal.
firmwareVersionstring
Firmware version of the physical device.
modelstringrequired
Model of the device that the merchant used to process the transaction.bbposChpbbposChp2xbbposChp3xbbposRamblerbbposWpbbposWp2bbposWp3genericCtlsMsr+32 more
serialNumberstringrequired
Serial number of the physical device.1–64 chars
dataKsnstringhexadecimalrequired
Key serial number.20–20 chars
encryptedDatastringhexadecimalrequired
Encrypted data received from the magnetic stripe reader.1–2147483647 chars
fallbackboolean
Indicates that this is a fallback transaction. For example, if there was a technical issue with the chip on the customer's card and the merchant then swiped the card.
fallbackReasonstring
Reason for the fallback.technicalrepeatFallbackemptyCandidateList
firstDigitOfPanstring
First digit of the of the card number.1–1 chars
plainTextobject
Object that contains information about plain-text swiped card data.
dataFormatstringrequired
Indicates the method the customer’s card data is encrypted. Send swiped card data in encrypted format or plainText format.plainText
deviceobjectrequired
Object that contains information about the physical device the merchant used to capture the customer’s card details.
categorystring
Indicates if the device is attended or unattended.attendedunattended
configobject
Object that contains information about the configuration of the POS terminal.
quickChipbooleanrequired
Indicates if Quick Chip mode is active on a merchant’s POS terminal.
firmwareVersionstring
Firmware version of the physical device.
modelstringrequired
Model of the device that the merchant used to process the transaction.bbposChpbbposChp2xbbposChp3xbbposRamblerbbposWpbbposWp2bbposWp3genericCtlsMsr+32 more
serialNumberstringrequired
Serial number of the physical device.1–64 chars
fallbackboolean
Indicates that this is a fallback transaction. For example, if there was a technical issue with the chip on the customer's card and the merchant then swiped the card.
fallbackReasonstring
Reason for the fallback.technicalrepeatFallbackemptyCandidateList
trackDatastringrequired
Customer’s card data from the swiped transaction.16–256 chars
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
Responses
Successful request. We processed the refund.
201 Created · application/json
{"card":{"cardNumber":"453985******7062","entryMethod":"keyed","expiryDate":"1230","type":"Visa Credit"},"customFields":[{"name":"yourCustomField","value":"abc123"}],"order":{"amount":4999,"currency":"USD","dateTime":"2024-07-02T15:30:00Z","description":"Refund for order OrderRef6543","orderId":"OrderRef6543"},"processingTerminalId":"1234001","refundId":"CD3HN88U9F","transactionResult":{"approvalCode":"000000","authorizedAmount":-4999,"currency":"USD","responseCode":"A","responseMessage":"OK5","status":"ready","type":"refund"}}
Response schema · 112 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
Masked card number. 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.
entryMethodstring
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.
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.
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 that the card is linked to. 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
typestringrequired
Type of contact method.email
valuestringrequired
Email address.≤ 50 chars
phoneobject
typestringrequired
Type of contact method.phone
valuestringrequired
Phone number.≤ 15 chars
mobileobject
typestringrequired
Type of contact method.mobile
valuestringrequired
Mobile number.≤ 15 chars
faxobject
typestringrequired
Type of contact method.fax
valuestringrequired
Fax number.≤ 15 chars
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.
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
recipientNamestring
Recipient's name.0–50 chars
operatorstring
Operator who requested the refund.0–50 chars
orderobjectrequired
Object that contains information about the refund.
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.
descriptionstringrequired
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.
paymentobject
Object that contains information about a payment.
amountintegerint64required
Amount of the payment. 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 payment 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.
paymentIdstringrequired
Unique identifier of the payment.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
responseMessagestring
Response description from the processor.1–48 chars
statusstringrequired
Current status of the payment.readypendingdeclinedcompletereferralpickupreversalreturned+3 more
processingTerminalIdstringrequired
Unique identifier that we assigned to the terminal.4–50 chars
refundIdstringrequired
Unique identifier that our gateway assigned to the refund.10–10 chars
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
{"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"}