Paymend API documentation

cURL

curl --request POST \
  --url http://localhost:8080/api/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 12997,
  "currency": "USD",
  "paymentMethod": {
    "type": "CARD",
    "card": {
      "number": "4111111111111111",
      "holderName": "John Doe",
      "expiryMonth": "12",
      "expiryYear": "2025",
      "cvv": "123",
      "brand": "VISA"
    }
  },
  "merchantReference": "PAYMENT-12345",
  "goodsType": "MIXED",
  "captureNow": true,
  "descriptor": "MyStore Online",
  "productItems": [
    {
      "id": "PROD-001",
      "name": "Wireless Keyboard",
      "quantity": 2,
      "unitPrice": 4999,
      "goodsType": "PHYSICAL"
    },
    {
      "id": "PROD-002",
      "name": "E-Book Subscription",
      "quantity": 1,
      "unitPrice": 2999,
      "goodsType": "DIGITAL"
    }
  ],
  "consumer": {
    "firstName": "John",
    "email": "[email protected]",
    "lastName": "Doe",
    "phone": "+1234567890",
    "ip": "192.168.1.1"
  },
  "billing": {
    "address": {
      "street": "123 Main Street",
      "city": "San Francisco",
      "country": "US",
      "state": "CA",
      "zip": "94105"
    }
  },
  "shipping": {
    "address": {
      "street": "123 Main Street",
      "city": "San Francisco",
      "country": "US",
      "state": "CA",
      "zip": "94105"
    },
    "firstName": "Jane",
    "lastName": "Smith"
  },
  "previousFailures": [
    {
      "gateway": "AcquirerX",
      "attemptNumber": 1,
      "responseCode": "05",
      "reason": "Do not honour",
      "timestamp": "2025-11-05T14:22:10Z"
    },
    {
      "gateway": "ProcessorY",
      "attemptNumber": 2,
      "responseCode": "14",
      "reason": "Invalid card number",
      "timestamp": "2025-11-05T14:24:32Z"
    }
  ]
}
'

{
  "paymentId": "pay_1234567890abcdef",
  "merchantReference": "ORDER-12345",
  "amount": 12997,
  "currency": "USD",
  "status": "CAPTURED",
  "paymentMethod": {
    "type": "CARD",
    "card": {
      "bin": "41111111",
      "holderName": "John Doe",
      "expiryMonth": "12",
      "expiryYear": "2025",
      "last4": "1111",
      "cvvPresentDuringAttempt": true,
      "brand": "VISA"
    }
  },
  "captureNow": true,
  "descriptor": "MyStore Online",
  "goodsType": "MIXED",
  "productItems": [
    {
      "id": "PROD-001",
      "name": "Wireless Keyboard",
      "quantity": 2,
      "unitPrice": 4999,
      "goodsType": "PHYSICAL"
    },
    {
      "id": "PROD-002",
      "name": "E-Book Subscription",
      "quantity": 1,
      "unitPrice": 2999,
      "goodsType": "DIGITAL"
    }
  ],
  "consumer": {
    "firstName": "John",
    "email": "[email protected]",
    "lastName": "Doe",
    "phone": "+1234567890",
    "ip": "192.168.1.1"
  },
  "billing": {
    "address": {
      "street": "123 Main Street",
      "city": "San Francisco",
      "country": "US",
      "state": "CA",
      "zip": "94105"
    }
  },
  "shipping": {
    "address": {
      "street": "123 Main Street",
      "city": "San Francisco",
      "country": "US",
      "state": "CA",
      "zip": "94105"
    },
    "firstName": "Jane",
    "lastName": "Smith"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T11:00:00Z"
}

POST

api

payments

cURL

curl --request POST \
  --url http://localhost:8080/api/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 12997,
  "currency": "USD",
  "paymentMethod": {
    "type": "CARD",
    "card": {
      "number": "4111111111111111",
      "holderName": "John Doe",
      "expiryMonth": "12",
      "expiryYear": "2025",
      "cvv": "123",
      "brand": "VISA"
    }
  },
  "merchantReference": "PAYMENT-12345",
  "goodsType": "MIXED",
  "captureNow": true,
  "descriptor": "MyStore Online",
  "productItems": [
    {
      "id": "PROD-001",
      "name": "Wireless Keyboard",
      "quantity": 2,
      "unitPrice": 4999,
      "goodsType": "PHYSICAL"
    },
    {
      "id": "PROD-002",
      "name": "E-Book Subscription",
      "quantity": 1,
      "unitPrice": 2999,
      "goodsType": "DIGITAL"
    }
  ],
  "consumer": {
    "firstName": "John",
    "email": "[email protected]",
    "lastName": "Doe",
    "phone": "+1234567890",
    "ip": "192.168.1.1"
  },
  "billing": {
    "address": {
      "street": "123 Main Street",
      "city": "San Francisco",
      "country": "US",
      "state": "CA",
      "zip": "94105"
    }
  },
  "shipping": {
    "address": {
      "street": "123 Main Street",
      "city": "San Francisco",
      "country": "US",
      "state": "CA",
      "zip": "94105"
    },
    "firstName": "Jane",
    "lastName": "Smith"
  },
  "previousFailures": [
    {
      "gateway": "AcquirerX",
      "attemptNumber": 1,
      "responseCode": "05",
      "reason": "Do not honour",
      "timestamp": "2025-11-05T14:22:10Z"
    },
    {
      "gateway": "ProcessorY",
      "attemptNumber": 2,
      "responseCode": "14",
      "reason": "Invalid card number",
      "timestamp": "2025-11-05T14:24:32Z"
    }
  ]
}
'

{
  "paymentId": "pay_1234567890abcdef",
  "merchantReference": "ORDER-12345",
  "amount": 12997,
  "currency": "USD",
  "status": "CAPTURED",
  "paymentMethod": {
    "type": "CARD",
    "card": {
      "bin": "41111111",
      "holderName": "John Doe",
      "expiryMonth": "12",
      "expiryYear": "2025",
      "last4": "1111",
      "cvvPresentDuringAttempt": true,
      "brand": "VISA"
    }
  },
  "captureNow": true,
  "descriptor": "MyStore Online",
  "goodsType": "MIXED",
  "productItems": [
    {
      "id": "PROD-001",
      "name": "Wireless Keyboard",
      "quantity": 2,
      "unitPrice": 4999,
      "goodsType": "PHYSICAL"
    },
    {
      "id": "PROD-002",
      "name": "E-Book Subscription",
      "quantity": 1,
      "unitPrice": 2999,
      "goodsType": "DIGITAL"
    }
  ],
  "consumer": {
    "firstName": "John",
    "email": "[email protected]",
    "lastName": "Doe",
    "phone": "+1234567890",
    "ip": "192.168.1.1"
  },
  "billing": {
    "address": {
      "street": "123 Main Street",
      "city": "San Francisco",
      "country": "US",
      "state": "CA",
      "zip": "94105"
    }
  },
  "shipping": {
    "address": {
      "street": "123 Main Street",
      "city": "San Francisco",
      "country": "US",
      "state": "CA",
      "zip": "94105"
    },
    "firstName": "Jane",
    "lastName": "Smith"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T11:00:00Z"
}

Authorizations

Authorization

string

header

required

Enter your API token

Headers

User-Agent

string

Body

application/json

amount

integer

required

Payment amount in the smallest currency unit (e.g., cents).

Example:

12997

currency

string

required

Three-letter ISO 4217 currency code (e.g., USD, EUR).

Example:

"USD"

paymentMethod

object

required

The chosen payment method details (e.g., card).

Show child attributes

paymentMethod.type

enum<string>

required

Payment method type. Currently, only CARD is supported. In future versions, additional types such as PAYPAL, APPLE_PAY, or BANK_TRANSFER may be introduced.

Available options:

CARD

Example:

"CARD"

paymentMethod.card

object

Card details (required if type=CARD).

Show child attributes

paymentMethod.card.number

string

required

Card number (PAN), digits only.

Example:

"4111111111111111"

paymentMethod.card.holderName

string

required

Name printed on the card.

Example:

"John Doe"

paymentMethod.card.expiryMonth

string

required

Expiry month of the card, in MM format (01–12).

Example:

"12"

paymentMethod.card.expiryYear

string

required

Expiry year of the card, in YYYY format.

Example:

"2025"

paymentMethod.card.cvv

string

Card verification value (CVV/CVC). Required for most transactions. Note: This field is masked in API responses for security.

Example:

"123"

paymentMethod.card.brand

string

Card brand (e.g., VISA, MASTERCARD).

Example:

"VISA"

merchantReference

string

required

Merchant's unique identifier for this payment (idempotency/business tracking).

Example:

"PAYMENT-12345"

goodsType

enum<string>

required

Type of goods being purchased: PHYSICAL = tangible items, DIGITAL = non-physical items, MIXED = combination of both.

Available options:

PHYSICAL,

DIGITAL,

MIXED

Example:

"MIXED"

captureNow

boolean

Determines how the payment is processed. Default: false → Authorization only (funds reserved, must capture later). If true → Sale (authorize and capture in one step).

Example:

true

descriptor

string

Text shown on the customer's bank statement (e.g., merchant or product name).

Example:

"MyStore Online"

productItems

object[]

List of product or service items included in this payment.

Show child attributes

productItems.id

string

required

Unique identifier of the product or service in the merchant's catalog.

Example:

"PROD-001"

productItems.name

string

required

Name or description of the item.

Example:

"Wireless Keyboard"

productItems.quantity

integer

required

Quantity of this item being purchased.

Required range: x >= 1

Example:

2

productItems.unitPrice

integer

required

Unit price in the smallest currency unit (e.g., cents).

Required range: x >= 1

Example:

1999

productItems.goodsType

enum<string>

required

Type of item — physical or digital goods.

Available options:

PHYSICAL,

DIGITAL

Example:

"PHYSICAL"

Example:

[
  {
    "id": "PROD-001",
    "name": "Wireless Keyboard",
    "quantity": 2,
    "unitPrice": 4999,
    "goodsType": "PHYSICAL"
  },
  {
    "id": "PROD-002",
    "name": "E-Book Subscription",
    "quantity": 1,
    "unitPrice": 2999,
    "goodsType": "DIGITAL"
  }
]

consumer

object

Consumer details such as name, email, phone.

Show child attributes

consumer.firstName

string

required

Consumer's first name.

Example:

"John"

consumer.email

string

required

Consumer's email address.

Example:

"[email protected]"

consumer.lastName

string

Consumer's last name.

Example:

"Doe"

consumer.phone

string

Consumer's phone number (E.164 format recommended).

Example:

"+1234567890"

consumer.ip

string

Consumer's IP address at the time of purchase.

Example:

"192.168.1.1"

billing

object

Billing address information.

Show child attributes

billing.address

object

required

Billing address details.

Show child attributes

billing.address.street

string

Street address line.

Example:

"123 Main Street"

billing.address.city

string

City or locality.

Example:

"San Francisco"

billing.address.country

string

Two-letter ISO 3166 country code (e.g., US, DE).

Example:

"US"

billing.address.state

string

State, province, or region.

Example:

"CA"

billing.address.zip

string

ZIP or postal code.

Example:

"94105"

shipping

object

Shipping address and recipient details.

Show child attributes

shipping.address

object

Shipping address details.

Show child attributes

shipping.address.street

string

Street address line.

Example:

"123 Main Street"

shipping.address.city

string

City or locality.

Example:

"San Francisco"

shipping.address.country

string

Two-letter ISO 3166 country code (e.g., US, DE).

Example:

"US"

shipping.address.state

string

State, province, or region.

Example:

"CA"

shipping.address.zip

string

ZIP or postal code.

Example:

"94105"

shipping.firstName

string

Recipient's first name.

Example:

"Jane"

shipping.lastName

string

Recipient's last name.

Example:

"Smith"

previousFailures

object[]

Array of previous failed payment attempts with other providers.

Show child attributes

previousFailures.gateway

string

Name or identifier of the provider where the failure occurred.

Example:

"AcquirerX"

previousFailures.attempt_number

integer

Sequential number of this attempt.

Example:

1

previousFailures.response_code

string

Provider-specific failure or decline code.

Example:

"05"

previousFailures.reason

string

Human-readable reason for the failure.

Example:

"Do not honour"

previousFailures.timestamp

string<date-time>

When the failure occurred.

Example:

"2025-11-05T14:22:10Z"

previousFailures.transaction_id

string

Transaction identifier from the original provider.

Example:

"txn_abc123"

previousFailures.additional_data

object

Additional gateway-specific data.

Example:

{ "avs_result": "N", "cvv_result": "N" }

Example:

[
  {
    "gateway": "AcquirerX",
    "attemptNumber": 1,
    "responseCode": "05",
    "reason": "Do not honour",
    "timestamp": "2025-11-05T14:22:10Z"
  },
  {
    "gateway": "ProcessorY",
    "attemptNumber": 2,
    "responseCode": "14",
    "reason": "Invalid card number",
    "timestamp": "2025-11-05T14:24:32Z"
  }
]

Response

paymentId

string

Unique identifier for the payment generated by the system.

Example:

"pay_1234567890abcdef"

merchantReference

string

Reference passed in by the merchant for correlation.

Example:

"ORDER-12345"

amount

integer

Amount processed in the smallest currency unit.

Example:

12997

currency

string

ISO 4217 currency code used in the payment.

Example:

"USD"

status

enum<string>

Current state of the payment.

Available options:

PENDING,

AUTHORIZED,

CAPTURED,

REFUNDED,

VOIDED,

FAILED

Example:

"CAPTURED"

paymentMethod

object

The chosen payment method details (e.g., card). Sensitive fields are masked in responses.

Show child attributes

paymentMethod.type

string

required

Payment method type. Currently, only CARD is supported. In future versions, additional types such as PAYPAL, APPLE_PAY, or BANK_TRANSFER may be introduced.

Example:

"CARD"

paymentMethod.card

object

Card details (required if type=CARD). Sensitive fields are masked in responses.

Show child attributes

paymentMethod.card.bin

string

required

Bank Identification Number (BIN) - first 8 digits for Visa/Mastercard, first 6 digits for Amex.

Example:

"41111111"

paymentMethod.card.holderName

string

required

Name printed on the card.

Example:

"John Doe"

paymentMethod.card.expiryMonth

string

required

Expiry month of the card, in MM format (01–12).

Example:

"12"

paymentMethod.card.expiryYear

string

required

Expiry year of the card, in YYYY format.

Example:

"2025"

paymentMethod.card.last4

string

Last 4 digits of the card number.

Example:

"1111"

paymentMethod.card.cvvPresentDuringAttempt

boolean

Indicates whether CVV was provided during the payment attempt.

Example:

true

paymentMethod.card.brand

string

Card brand (e.g., VISA, MASTERCARD).

Example:

"VISA"

captureNow

boolean

Determines how the payment is processed. Default: false → Authorization only (funds reserved, must capture later). If true → Sale (authorize and capture in one step).

Example:

true

descriptor

string

Text shown on the customer's bank statement (e.g., merchant or product name).

Example:

"MyStore Online"

goodsType

enum<string>

Type of goods being purchased: PHYSICAL = tangible items, DIGITAL = non-physical items, MIXED = combination of both.

Available options:

PHYSICAL,

DIGITAL,

MIXED

Example:

"MIXED"

productItems

object[]

List of product or service items included in this payment.

Show child attributes

productItems.id

string

required

Unique identifier of the product or service in the merchant's catalog.

Example:

"PROD-001"

productItems.name

string

required

Name or description of the item.

Example:

"Wireless Keyboard"

productItems.quantity

integer

required

Quantity of this item being purchased.

Required range: x >= 1

Example:

2

productItems.unitPrice

integer

required

Unit price in the smallest currency unit (e.g., cents).

Required range: x >= 1

Example:

1999

productItems.goodsType

enum<string>

required

Type of item — physical or digital goods.

Available options:

PHYSICAL,

DIGITAL

Example:

"PHYSICAL"

Example:

[
  {
    "id": "PROD-001",
    "name": "Wireless Keyboard",
    "quantity": 2,
    "unitPrice": 4999,
    "goodsType": "PHYSICAL"
  },
  {
    "id": "PROD-002",
    "name": "E-Book Subscription",
    "quantity": 1,
    "unitPrice": 2999,
    "goodsType": "DIGITAL"
  }
]

consumer

object

Consumer details such as name, email, phone.

Show child attributes

consumer.firstName

string

required

Consumer's first name.

Example:

"John"

consumer.email

string

required

Consumer's email address.

Example:

"[email protected]"

consumer.lastName

string

Consumer's last name.

Example:

"Doe"

consumer.phone

string

Consumer's phone number (E.164 format recommended).

Example:

"+1234567890"

consumer.ip

string

Consumer's IP address at the time of purchase.

Example:

"192.168.1.1"

billing

object

Billing address information.

Show child attributes

billing.address

object

required

Billing address details.

Show child attributes

billing.address.street

string

Street address line.

Example:

"123 Main Street"

billing.address.city

string

City or locality.

Example:

"San Francisco"

billing.address.country

string

Two-letter ISO 3166 country code (e.g., US, DE).

Example:

"US"

billing.address.state

string

State, province, or region.

Example:

"CA"

billing.address.zip

string

ZIP or postal code.

Example:

"94105"

shipping

object

Shipping address and recipient details.

Show child attributes

shipping.address

object

Shipping address details.

Show child attributes

shipping.address.street

string

Street address line.

Example:

"123 Main Street"

shipping.address.city

string

City or locality.

Example:

"San Francisco"

shipping.address.country

string

Two-letter ISO 3166 country code (e.g., US, DE).

Example:

"US"

shipping.address.state

string

State, province, or region.

Example:

"CA"

shipping.address.zip

string

ZIP or postal code.

Example:

"94105"

shipping.firstName

string

Recipient's first name.

Example:

"Jane"

shipping.lastName

string

Recipient's last name.

Example:

"Smith"

createdAt

string<date-time>

Timestamp when the payment was created.

Example:

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

updatedAt

string<date-time>

Timestamp when the payment was last updated.

Example:

"2024-01-15T11:00:00Z"

Getting Started Get payment

⌘I

API documentation

Endpoints

API Objects

Create payment

Authorizations

Headers

Body

Response