Skip to main content
POST
/
payment-methods
Create a payment method
curl --request POST \
  --url http://localhost:3156/payment-methods \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-merchant-id: <api-key>' \
  --data '
{
  "type": "CARD",
  "cardDetails": {
    "cardNumber": "4111111111111111",
    "cvc": "123",
    "expMonth": 12,
    "expYear": 25
  },
  "customerId": "123e4567-e89b-12d3-a456-426614174000",
  "merchantId": "merchant_123",
  "isDefault": false,
  "nickname": "My Visa Card",
  "billingFirstName": "John",
  "billingLastName": "Doe",
  "billingPhoneNumber": "+525512345678",
  "billingEmail": "[email protected]",
  "billingAddressLine1": "123 Main St",
  "billingAddressLine2": "Apt 4B",
  "billingCity": "Mexico City",
  "billingState": "CDMX",
  "billingPostalCode": "12345",
  "billingCountry": "MX",
  "persist": true
}
'
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "type": "CARD",
  "isDefault": false,
  "createdAt": "2025-01-15T10:00:00.000Z",
  "updatedAt": "2025-01-15T10:00:00.000Z",
  "nickname": "My Visa Card",
  "billingFirstName": "John",
  "billingLastName": "Doe",
  "billingPhoneNumber": "+525512345678",
  "billingEmail": "[email protected]",
  "billingAddressLine1": "123 Main St",
  "billingAddressLine2": "Apt 4B",
  "billingCity": "Mexico City",
  "billingState": "CDMX",
  "billingPostalCode": "12345",
  "billingCountry": "MX",
  "cardDetails": {
    "last4": "1111",
    "bin": "411111",
    "expMonth": 12,
    "expYear": 25,
    "type": "credit",
    "brand": "VISA",
    "country": "US",
    "issuerBank": "Chase Bank"
  }
}

Authorizations

​
x-api-key
string
header
required

API key for authentication (required)

​
x-merchant-id
string
header
required

Merchant ID for identifying the merchant (required)

Body

application/json
​
type
enum<string>
required

Payment method type (currently only CARD is supported)

Available options:
CARD
Example:

"CARD"

​
cardDetails
object
required
​
customerId
string

Customer ID to associate this payment method with

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
merchantId
string

Merchant ID (optional, defaults to global merchant ID)

Example:

"merchant_123"

​
isDefault
boolean

Whether this is the default payment method for the customer

Example:

false

​
nickname
string

Optional nickname for the payment method

Example:

"My Visa Card"

​
billingFirstName
string

Billing first name

Example:

"John"

​
billingLastName
string

Billing last name

Example:

"Doe"

​
billingPhoneNumber
string

Billing phone number

Example:

"+525512345678"

​
billingEmail
string<email>

Billing email address

Example:

"[email protected]"

​
billingAddressLine1
string

Billing address line 1

Example:

"123 Main St"

​
billingAddressLine2
string

Billing address line 2

Example:

"Apt 4B"

​
billingCity
string

Billing city

Example:

"Mexico City"

​
billingState
string

Billing state

Example:

"CDMX"

​
billingPostalCode
string

Billing postal code

Example:

"12345"

​
billingCountry
string

Billing country code (2 characters)

Required string length: 2
Example:

"MX"

​
persist
boolean
default:true

Whether to persist the payment method (requires customerId if true)

Example:

true

Response

Payment method created successfully

​
id
string
required

Payment method ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
type
string
required

Payment method type

Example:

"CARD"

​
isDefault
boolean
required

Whether this is the default payment method

Example:

false

​
createdAt
string<date-time>
required

Creation timestamp

Example:

"2025-01-15T10:00:00.000Z"

​
updatedAt
string<date-time>
required

Last update timestamp

Example:

"2025-01-15T10:00:00.000Z"

​
nickname
string

Payment method nickname

Example:

"My Visa Card"

​
billingFirstName
string

Billing first name

Example:

"John"

​
billingLastName
string

Billing last name

Example:

"Doe"

​
billingPhoneNumber
string

Billing phone number

Example:

"+525512345678"

​
billingEmail
string

Billing email address

Example:

"[email protected]"

​
billingAddressLine1
string

Billing address line 1

Example:

"123 Main St"

​
billingAddressLine2
string

Billing address line 2

Example:

"Apt 4B"

​
billingCity
string

Billing city

Example:

"Mexico City"

​
billingState
string

Billing state

Example:

"CDMX"

​
billingPostalCode
string

Billing postal code

Example:

"12345"

​
billingCountry
string

Billing country code

Example:

"MX"

​
cardDetails
object