Skip to main content
POST
/
simulation
/
card-transactions
/
decline
Simulate decline
curl --request POST \
  --url https://sandbox.api.reap.global/simulation/card-transactions/decline \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Reap-Version: <reap-version>' \
  --data '
{
  "cardId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "amount": 1,
  "transactionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "originalAmount": 1,
  "originalCurrency": "<string>",
  "channel": "ATM",
  "digitalWallet": "APPLE_PAY",
  "merchant": {
    "name": "<string>",
    "city": "<string>",
    "country": "<string>",
    "mccCode": "<string>",
    "mccCategory": "<string>"
  },
  "declineReason": "INSUFFICIENT_BALANCE"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "cardId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "channel": "ATM",
  "digitalWallet": "APPLE_PAY",
  "originalCurrency": "<string>",
  "currency": "<string>",
  "merchant": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "city": "<string>",
    "mccCode": "<string>",
    "mccCategory": "<string>",
    "country": "<string>"
  },
  "events": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "AUTHORIZATION",
      "originalAmount": 1,
      "originalCurrency": "<string>",
      "amount": 1,
      "occurredAt": "<string>",
      "createdAt": "<string>"
    }
  ],
  "occurredAt": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "status": "<string>",
  "originalAmount": {
    "authorized": 1,
    "reversed": 1,
    "current": 1
  },
  "amount": {
    "authorized": 1,
    "reversed": 1,
    "current": 1
  },
  "conversionRate": 1
}

Authorizations

​
Authorization
string
header
required

API key as Bearer token

Headers

​
Reap-Version
enum<string>
required

API version (YYYY-MM-DD)

Available options:
2025-02-14
Example:

"2025-02-14"

Body

Simulate a decline event on a card

​
cardId
string<uuid>
required

Card ID

​
amount
number
required

Amount in USD

Required range: x >= 0
​
transactionId
string<uuid>

Existing transaction ID. Omit to create a new declined transaction.

​
originalAmount
number

Amount in the original transaction currency. Must be provided together with originalCurrency.

Required range: x >= 0
​
originalCurrency
string

Original transaction currency (ISO 4217). Must be provided together with originalAmount.

Required string length: 3
​
channel
enum<string>

Transaction channel. Randomly generated if omitted.

Available options:
ATM,
POS,
ECOMMERCE,
VISA_DIRECT
Example:

"ATM"

​
digitalWallet
enum<string>

Digital wallet type (e.g. APPLE_PAY, GOOGLE_PAY). Randomly generated if omitted.

Available options:
APPLE_PAY,
GOOGLE_PAY,
MERCHANT_TOKEN
Example:

"APPLE_PAY"

​
merchant
object

Merchant details. All fields are optional and will be randomly generated if omitted.

​
declineReason
enum<string>

Decline reason code. Defaults to INSUFFICIENT_BALANCE.

Available options:
INSUFFICIENT_BALANCE,
INSUFFICIENT_MASTER_BALANCE,
CARD_NOT_ACTIVE,
CARD_NOT_ACTIVATED,
CARD_EXPIRED,
CARD_FROZEN,
CARD_BLOCKED,
CARD_REPORTED_LOST,
CARD_REPORTED_STOLEN,
ACCOUNT_NOT_ACTIVE,
INCORRECT_PIN,
INCORRECT_CVV,
INVALID_CARD_DETAILS,
CONTACTLESS_NOT_SUPPORTED,
TERMINAL_ERROR,
CASH_SERVICE_NOT_AVAILABLE,
WITHDRAWALS_NOT_ALLOWED,
ATM_COUNTRY_RESTRICTED,
ATM_WITHDRAWAL_LIMIT_EXCEEDED,
ATM_WITHDRAWAL_FREQUENCY_EXCEEDED,
MERCHANT_CARD_TYPE_MISMATCH,
MERCHANT_CATEGORY_CODE_NOT_ALLOWED,
TRANSACTION_TYPE_NOT_ALLOWED,
NETWORK_DECLINE,
SUSPECTED_FRAUD,
INTERNAL_ERROR
Example:

"INSUFFICIENT_BALANCE"

Response

Card transaction resource. The response shape varies by transaction status.

Authorized transaction that hasn't settled yet

​
id
string<uuid>
required

Card transaction identifier

​
accountId
string<uuid>
required

Account linked to the card

​
cardId
string<uuid>
required

Card used for this transaction

​
channel
enum<string>
required

Transaction channel

Available options:
ATM,
POS,
ECOMMERCE,
VISA_DIRECT
Example:

"ATM"

​
digitalWallet
enum<string> | null
required

Digital wallet used, or null if physical card

Available options:
APPLE_PAY,
GOOGLE_PAY,
MERCHANT_TOKEN
Example:

"APPLE_PAY"

​
originalCurrency
string
required

Original transaction currency (merchant local currency)

Examples:

"USD"

"HKD"

"EUR"

​
currency
string
required

Card currency

Examples:

"USD"

"HKD"

"EUR"

​
merchant
object
required

Merchant details

​
events
object[]
required

Chronologically sorted lifecycle events (oldest first). Provides the full audit trail of what happened to this transaction.

​
occurredAt
string
required

ISO 8601 timestamp of when the transaction was initiated

Example:

"2024-01-15T10:30:00Z"

​
createdAt
string
required

ISO 8601 timestamp of creation

Example:

"2024-01-15T10:30:00Z"

​
updatedAt
string
required

ISO 8601 timestamp of last update

Example:

"2024-01-15T10:35:00Z"

​
status
string
required
Allowed value: "PENDING"
​
originalAmount
object
required

Amount in the original transaction currency

​
amount
object
required

Amount charged to the cardholder

​
conversionRate
number
required

Conversion rate from the original currency to the card currency

Required range: x >= 0
Examples:

1

0.128205

7.812