Skip to main content
POST
/
payment-method
Create a payment method
curl --request POST \
  --url https://demo.api.harmony.compago.com/api/payment-method \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "billingInformation": {
    "email": "maria.gonzalez@example.com",
    "firstName": "María",
    "lastName": "González",
    "phoneNumber": "+5215512345678"
  },
  "externalId": "customer_12345",
  "verificationAmount": 1,
  "displayMode": "LINK",
  "buttonText": "<string>",
  "buttonColor": "<string>",
  "redirectUrl": "https://yourstore.com/cards/saved",
  "ttlMinutes": 2880
}
'
{
  "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "checkoutUrl": "<string>"
}

Authorizations

​
x-api-key
string
header
required

Body

application/json

Request body for creating a payment method. The customer will be directed to the checkout URL to securely save their card. A small verification charge is placed and then voided to validate the card.

​
billingInformation
object
required

Billing information for the payment method

​
externalId
string

Optional external ID to track the payment method in your system.

Example:

"customer_12345"

​
verificationAmount
number<decimal>
default:1

Amount in MXN used for the verification charge. This charge is placed and then voided. Defaults to $1 MXN.

Required range: x >= 0.01
Example:

1

​
displayMode
enum<string>
default:LINK

How the checkout is displayed. LINK redirects the customer to a full-page checkout. EMBEDDED allows embedding in an iframe.

Available options:
LINK,
EMBEDDED
​
buttonText
string

Custom text for the checkout button (EMBEDDED mode only).

​
buttonColor
string

Custom hex color for the checkout button (EMBEDDED mode only).

​
redirectUrl
string<uri>

URL where the customer is redirected after successfully saving their card. Compago appends id and externalId as query parameters.

Example:

"https://yourstore.com/cards/saved"

​
ttlMinutes
integer
default:2880

Time-to-live in minutes for the checkout link. Defaults to 2,880 minutes (48 hours).

Required range: x >= 1
Example:

2880

Response

Payment method created successfully

Response after creating a payment method

​
id
string<uuid>
required

Unique identifier of the payment method

Example:

"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"

​
checkoutUrl
string<uri>
required

URL where the customer completes the card saving process