Paymend API documentation

cURL

curl --request POST \
  --url http://localhost:8080/api/v1/payments/{paymentId}/refund \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "refundAmount": 12997
}
'

{
  "paymentId": "pay_1234567890abcdef",
  "merchantReference": "ORDER-12345",
  "amount": 12997,
  "currency": "USD",
  "status": "REFUNDED",
  "paymentMethod": {
    "type": "card",
    "card": {
      "bin": "41111111",
      "holderName": "John Doe",
      "cvvPresentDuringAttempt": true,
      "expiryMonth": "12",
      "expiryYear": "2025",
      "brand": "VISA"
    }
  },
  "captureNow": false,
  "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",
    "lastName": "Doe",
    "email": "[email protected]"
  },
  "billing": {
    "firstName": "John",
    "lastName": "Doe",
    "address": {
      "line1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  },
  "shipping": {
    "firstName": "John",
    "lastName": "Doe",
    "address": {
      "line1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T11:00:00Z"
}

POST

api

payments

{paymentId}

refund

cURL

curl --request POST \
  --url http://localhost:8080/api/v1/payments/{paymentId}/refund \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "refundAmount": 12997
}
'

{
  "paymentId": "pay_1234567890abcdef",
  "merchantReference": "ORDER-12345",
  "amount": 12997,
  "currency": "USD",
  "status": "REFUNDED",
  "paymentMethod": {
    "type": "card",
    "card": {
      "bin": "41111111",
      "holderName": "John Doe",
      "cvvPresentDuringAttempt": true,
      "expiryMonth": "12",
      "expiryYear": "2025",
      "brand": "VISA"
    }
  },
  "captureNow": false,
  "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",
    "lastName": "Doe",
    "email": "[email protected]"
  },
  "billing": {
    "firstName": "John",
    "lastName": "Doe",
    "address": {
      "line1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  },
  "shipping": {
    "firstName": "John",
    "lastName": "Doe",
    "address": {
      "line1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T11:00:00Z"
}

Authorizations

Authorization

string

header

required

Enter your API token

Path Parameters

paymentId

string

required

Body

application/json

Only required when performing a partial refund. For a full refund, this object can be omitted.

refundAmount

integer

Amount to refund in the smallest currency unit.

Required range: x >= 1

Example:

12997

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"

Capture payment Void payment

⌘I

API documentation

Endpoints

API Objects

Refund payment

Authorizations

Path Parameters

Body

Response