Register, verify, retrieve, list, and delete webhook endpoints that receive POST notifications for transaction events such as charge.succeeded, charge.refunded, charge.failed, and payout events.
openapi: 3.0.1
info:
title: Openpay API
description: >-
REST API for the Openpay online payments platform (BBVA group), available in
Mexico and Colombia. Resources are scoped to a merchant under the path
/v1/{merchant_id}. The API supports charges against cards, convenience stores
(cash), and banks (SPEI); customers and stored cards; client-side tokens;
recurring plans and subscriptions; payouts and transfers to bank accounts;
commission fees; and webhook notifications. Authentication uses HTTP Basic
auth with the merchant private API key as the username and an empty password.
termsOfService: https://www.openpay.mx/terminos-y-condiciones.html
contact:
name: Openpay Support
url: https://www.openpay.mx
email: soporte@openpay.mx
version: '1.0'
servers:
- url: https://api.openpay.mx/v1
description: Production (Mexico)
- url: https://sandbox-api.openpay.mx/v1
description: Sandbox (Mexico)
- url: https://api.openpay.co/v1
description: Production (Colombia)
- url: https://sandbox-api.openpay.co/v1
description: Sandbox (Colombia)
security:
- basicAuth: []
tags:
- name: Charges
description: Create and manage charges to cards, stores, and banks.
- name: Customers
description: Manage customer records.
- name: Cards
description: Store and manage cards at merchant or customer level.
- name: Tokens
description: Client-side tokenization of card data.
- name: Plans
description: Templates defining amount and frequency for recurring charges.
- name: Subscriptions
description: Associate customers and cards to plans for recurring billing.
- name: Payouts
description: Send funds to registered bank accounts.
- name: Transfers
description: Move funds between Openpay customers.
- name: BankAccounts
description: Manage customer bank accounts used as payout destinations.
- name: Fees
description: Charge commission fees to a customer's Openpay balance.
- name: Webhooks
description: Register and manage webhook endpoints for event notifications.
paths:
/{merchant_id}/charges:
parameters:
- $ref: '#/components/parameters/MerchantId'
post:
operationId: createMerchantCharge
tags:
- Charges
summary: Create a charge at the merchant level.
description: >-
Creates a charge against a card (saved card id, token, or raw card data),
a store (cash), or a bank (SPEI). For card charges, set capture=false to
authorize without capturing.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCharge'
responses:
'200':
description: Charge created.
content:
application/json:
schema:
$ref: '#/components/schemas/Charge'
'400':
$ref: '#/components/responses/Error'
'402':
$ref: '#/components/responses/Error'
get:
operationId: listMerchantCharges
tags:
- Charges
summary: List charges at the merchant level.
parameters:
- $ref: '#/components/parameters/Creation'
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: A list of charges.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Charge'
/{merchant_id}/charges/{transaction_id}:
parameters:
- $ref: '#/components/parameters/MerchantId'
- $ref: '#/components/parameters/TransactionId'
get:
operationId: getMerchantCharge
tags:
- Charges
summary: Get a charge by id.
responses:
'200':
description: The charge.
content:
application/json:
schema:
$ref: '#/components/schemas/Charge'
'404':
$ref: '#/components/responses/Error'
/{merchant_id}/charges/{transaction_id}/refund:
parameters:
- $ref: '#/components/parameters/MerchantId'
- $ref: '#/components/parameters/TransactionId'
post:
operationId: refundMerchantCharge
tags:
- Charges
summary: Refund a charge.
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/RefundRequest'
responses:
'200':
description: The refunded charge.
content:
application/json:
schema:
$ref: '#/components/schemas/Charge'
/{merchant_id}/charges/{transaction_id}/capture:
parameters:
- $ref: '#/components/parameters/MerchantId'
- $ref: '#/components/parameters/TransactionId'
post:
operationId: captureMerchantCharge
tags:
- Charges
summary: Capture a previously authorized charge.
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/CaptureRequest'
responses:
'200':
description: The captured charge.
content:
application/json:
schema:
$ref: '#/components/schemas/Charge'
/{merchant_id}/customers:
parameters:
- $ref: '#/components/parameters/MerchantId'
post:
operationId: createCustomer
tags:
- Customers
summary: Create a customer.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCustomer'
responses:
'200':
description: Customer created.
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
get:
operationId: listCustomers
tags:
- Customers
summary: List customers.
parameters:
- $ref: '#/components/parameters/Creation'
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: A list of customers.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Customer'
/{merchant_id}/customers/{customer_id}:
parameters:
- $ref: '#/components/parameters/MerchantId'
- $ref: '#/components/parameters/CustomerId'
get:
operationId: getCustomer
tags:
- Customers
summary: Get a customer by id.
responses:
'200':
description: The customer.
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
put:
operationId: updateCustomer
tags:
- Customers
summary: Update a customer.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCustomer'
responses:
'200':
description: The updated customer.
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
delete:
operationId: deleteCustomer
tags:
- Customers
summary: Delete a customer.
responses:
'204':
description: Customer deleted.
/{merchant_id}/customers/{customer_id}/charges:
parameters:
- $ref: '#/components/parameters/MerchantId'
- $ref: '#/components/parameters/CustomerId'
post:
operationId: createCustomerCharge
tags:
- Charges
summary: Create a charge at the customer level.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCharge'
responses:
'200':
description: Charge created.
content:
application/json:
schema:
$ref: '#/components/schemas/Charge'
get:
operationId: listCustomerCharges
tags:
- Charges
summary: List a customer's charges.
parameters:
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: A list of charges.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Charge'
/{merchant_id}/cards:
parameters:
- $ref: '#/components/parameters/MerchantId'
post:
operationId: createMerchantCard
tags:
- Cards
summary: Store a card at the merchant level.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCard'
responses:
'200':
description: Card stored.
content:
application/json:
schema:
$ref: '#/components/schemas/Card'
get:
operationId: listMerchantCards
tags:
- Cards
summary: List merchant-level cards.
responses:
'200':
description: A list of cards.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Card'
/{merchant_id}/cards/{card_id}:
parameters:
- $ref: '#/components/parameters/MerchantId'
- $ref: '#/components/parameters/CardId'
get:
operationId: getMerchantCard
tags:
- Cards
summary: Get a merchant-level card.
responses:
'200':
description: The card.
content:
application/json:
schema:
$ref: '#/components/schemas/Card'
delete:
operationId: deleteMerchantCard
tags:
- Cards
summary: Delete a merchant-level card.
responses:
'204':
description: Card deleted.
/{merchant_id}/customers/{customer_id}/cards:
parameters:
- $ref: '#/components/parameters/MerchantId'
- $ref: '#/components/parameters/CustomerId'
post:
operationId: createCustomerCard
tags:
- Cards
summary: Store a card for a customer.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCard'
responses:
'200':
description: Card stored.
content:
application/json:
schema:
$ref: '#/components/schemas/Card'
get:
operationId: listCustomerCards
tags:
- Cards
summary: List a customer's cards.
responses:
'200':
description: A list of cards.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Card'
/{merchant_id}/customers/{customer_id}/cards/{card_id}:
parameters:
- $ref: '#/components/parameters/MerchantId'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CardId'
get:
operationId: getCustomerCard
tags:
- Cards
summary: Get a customer's card.
responses:
'200':
description: The card.
content:
application/json:
schema:
$ref: '#/components/schemas/Card'
delete:
operationId: deleteCustomerCard
tags:
- Cards
summary: Delete a customer's card.
responses:
'204':
description: Card deleted.
/{merchant_id}/tokens:
parameters:
- $ref: '#/components/parameters/MerchantId'
post:
operationId: createToken
tags:
- Tokens
summary: Create a card token.
description: >-
Tokenizes card data so it does not pass through the merchant server,
reducing PCI scope. Typically called with the public API key from the
browser or device.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateToken'
responses:
'200':
description: Token created.
content:
application/json:
schema:
$ref: '#/components/schemas/Token'
/{merchant_id}/tokens/{token_id}:
parameters:
- $ref: '#/components/parameters/MerchantId'
- name: token_id
in: path
required: true
schema:
type: string
get:
operationId: getToken
tags:
- Tokens
summary: Get a token by id.
responses:
'200':
description: The token.
content:
application/json:
schema:
$ref: '#/components/schemas/Token'
/{merchant_id}/plans:
parameters:
- $ref: '#/components/parameters/MerchantId'
post:
operationId: createPlan
tags:
- Plans
summary: Create a plan.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePlan'
responses:
'200':
description: Plan created.
content:
application/json:
schema:
$ref: '#/components/schemas/Plan'
get:
operationId: listPlans
tags:
- Plans
summary: List plans.
parameters:
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: A list of plans.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Plan'
/{merchant_id}/plans/{plan_id}:
parameters:
- $ref: '#/components/parameters/MerchantId'
- name: plan_id
in: path
required: true
schema:
type: string
get:
operationId: getPlan
tags:
- Plans
summary: Get a plan by id.
responses:
'200':
description: The plan.
content:
application/json:
schema:
$ref: '#/components/schemas/Plan'
put:
operationId: updatePlan
tags:
- Plans
summary: Update a plan.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePlan'
responses:
'200':
description: The updated plan.
content:
application/json:
schema:
$ref: '#/components/schemas/Plan'
delete:
operationId: deletePlan
tags:
- Plans
summary: Delete a plan.
responses:
'204':
description: Plan deleted.
/{merchant_id}/customers/{customer_id}/subscriptions:
parameters:
- $ref: '#/components/parameters/MerchantId'
- $ref: '#/components/parameters/CustomerId'
post:
operationId: createSubscription
tags:
- Subscriptions
summary: Create a subscription for a customer.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSubscription'
responses:
'200':
description: Subscription created.
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
get:
operationId: listSubscriptions
tags:
- Subscriptions
summary: List a customer's subscriptions.
responses:
'200':
description: A list of subscriptions.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Subscription'
/{merchant_id}/customers/{customer_id}/subscriptions/{subscription_id}:
parameters:
- $ref: '#/components/parameters/MerchantId'
- $ref: '#/components/parameters/CustomerId'
- name: subscription_id
in: path
required: true
schema:
type: string
get:
operationId: getSubscription
tags:
- Subscriptions
summary: Get a subscription by id.
responses:
'200':
description: The subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
put:
operationId: updateSubscription
tags:
- Subscriptions
summary: Update a subscription.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSubscription'
responses:
'200':
description: The updated subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
delete:
operationId: cancelSubscription
tags:
- Subscriptions
summary: Cancel a subscription.
responses:
'204':
description: Subscription cancelled.
/{merchant_id}/customers/{customer_id}/bankaccounts:
parameters:
- $ref: '#/components/parameters/MerchantId'
- $ref: '#/components/parameters/CustomerId'
post:
operationId: createBankAccount
tags:
- BankAccounts
summary: Add a bank account to a customer.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBankAccount'
responses:
'200':
description: Bank account created.
content:
application/json:
schema:
$ref: '#/components/schemas/BankAccount'
get:
operationId: listBankAccounts
tags:
- BankAccounts
summary: List a customer's bank accounts.
responses:
'200':
description: A list of bank accounts.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BankAccount'
/{merchant_id}/customers/{customer_id}/bankaccounts/{bank_account_id}:
parameters:
- $ref: '#/components/parameters/MerchantId'
- $ref: '#/components/parameters/CustomerId'
- name: bank_account_id
in: path
required: true
schema:
type: string
get:
operationId: getBankAccount
tags:
- BankAccounts
summary: Get a bank account by id.
responses:
'200':
description: The bank account.
content:
application/json:
schema:
$ref: '#/components/schemas/BankAccount'
delete:
operationId: deleteBankAccount
tags:
- BankAccounts
summary: Delete a bank account.
responses:
'204':
description: Bank account deleted.
/{merchant_id}/customers/{customer_id}/payouts:
parameters:
- $ref: '#/components/parameters/MerchantId'
- $ref: '#/components/parameters/CustomerId'
post:
operationId: createPayout
tags:
- Payouts
summary: Create a payout to a registered bank account.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePayout'
responses:
'200':
description: Payout created.
content:
application/json:
schema:
$ref: '#/components/schemas/Payout'
get:
operationId: listPayouts
tags:
- Payouts
summary: List a customer's payouts.
parameters:
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: A list of payouts.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Payout'
/{merchant_id}/customers/{customer_id}/payouts/{payout_id}:
parameters:
- $ref: '#/components/parameters/MerchantId'
- $ref: '#/components/parameters/CustomerId'
- name: payout_id
in: path
required: true
schema:
type: string
get:
operationId: getPayout
tags:
- Payouts
summary: Get a payout by id.
responses:
'200':
description: The payout.
content:
application/json:
schema:
$ref: '#/components/schemas/Payout'
/{merchant_id}/customers/{customer_id}/transfers:
parameters:
- $ref: '#/components/parameters/MerchantId'
- $ref: '#/components/parameters/CustomerId'
post:
operationId: createTransfer
tags:
- Transfers
summary: Transfer funds from one customer to another.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTransfer'
responses:
'200':
description: Transfer created.
content:
application/json:
schema:
$ref: '#/components/schemas/Transfer'
get:
operationId: listTransfers
tags:
- Transfers
summary: List a customer's transfers.
responses:
'200':
description: A list of transfers.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Transfer'
/{merchant_id}/customers/{customer_id}/transfers/{transfer_id}:
parameters:
- $ref: '#/components/parameters/MerchantId'
- $ref: '#/components/parameters/CustomerId'
- name: transfer_id
in: path
required: true
schema:
type: string
get:
operationId: getTransfer
tags:
- Transfers
summary: Get a transfer by id.
responses:
'200':
description: The transfer.
content:
application/json:
schema:
$ref: '#/components/schemas/Transfer'
/{merchant_id}/fees:
parameters:
- $ref: '#/components/parameters/MerchantId'
post:
operationId: createFee
tags:
- Fees
summary: Charge a commission fee to a customer's balance.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateFee'
responses:
'200':
description: Fee charged.
content:
application/json:
schema:
$ref: '#/components/schemas/Fee'
get:
operationId: listFees
tags:
- Fees
summary: List charged fees.
parameters:
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: A list of fees.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Fee'
/{merchant_id}/webhooks:
parameters:
- $ref: '#/components/parameters/MerchantId'
post:
operationId: createWebhook
tags:
- Webhooks
summary: Register a webhook endpoint.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWebhook'
responses:
'200':
description: Webhook created (pending verification).
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
get:
operationId: listWebhooks
tags:
- Webhooks
summary: List registered webhooks.
responses:
'200':
description: A list of webhooks.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Webhook'
/{merchant_id}/webhooks/{webhook_id}:
parameters:
- $ref: '#/components/parameters/MerchantId'
- name: webhook_id
in: path
required: true
schema:
type: string
get:
operationId: getWebhook
tags:
- Webhooks
summary: Get a webhook by id.
responses:
'200':
description: The webhook.
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
delete:
operationId: deleteWebhook
tags:
- Webhooks
summary: Delete a webhook.
responses:
'204':
description: Webhook deleted.
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
HTTP Basic authentication. Use the merchant private API key as the
username and leave the password empty.
parameters:
MerchantId:
name: merchant_id
in: path
required: true
description: The merchant identifier that scopes all resources.
schema:
type: string
CustomerId:
name: customer_id
in: path
required: true
schema:
type: string
CardId:
name: card_id
in: path
required: true
schema:
type: string
TransactionId:
name: transaction_id
in: path
required: true
schema:
type: string
Creation:
name: creation
in: query
required: false
description: Filter by creation date (yyyy-mm-dd).
schema:
type: string
format: date
Offset:
name: offset
in: query
required: false
description: Number of records to skip for pagination.
schema:
type: integer
default: 0
Limit:
name: limit
in: query
required: false
description: Maximum number of records to return.
schema:
type: integer
default: 10
responses:
Error:
description: An Openpay error response.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
CreateCharge:
type: object
required:
- method
- amount
properties:
method:
type: string
enum:
- card
- store
- bank_account
description: The payment method for the charge.
source_id:
type: string
description: A stored card id or a token id (for card charges).
amount:
type: number
format: float
description: Charge amount in the merchant currency.
currency:
type: string
example: MXN
description:
type: string
order_id:
type: string
description: Unique merchant order identifier.
device_session_id:
type: string
description: Anti-fraud device session id captured client-side.
capture:
type: boolean
default: true
description: Set false to authorize without capturing.
customer:
$ref: '#/components/schemas/ChargeCustomer'
ChargeCustomer:
type: object
properties:
name:
type: string
last_name:
type: string
email:
type: string
phone_number:
type: string
Charge:
type: object
properties:
id:
type: string
authorization:
type: string
method:
type: string
operation_type:
type: string
example: in
transaction_type:
type: string
example: charge
status:
type: string
enum:
- completed
- in_progress
- failed
- cancelled
- refunded
amount:
type: number
format: float
currency:
type: string
description:
type: string
order_id:
type: string
creation_date:
type: string
format: date-time
operation_date:
type: string
format: date-time
card:
$ref: '#/components/schemas/Card'
payment_method:
$ref: '#/components/schemas/PaymentMethod'
error_message:
type: string
PaymentMethod:
type: object
description: >-
Method-specific payment details, present for store and bank charges
(e.g. reference, barcode_url, clabe, agreement, name).
properties:
type:
type: string
reference:
type: string
barcode_url:
type: string
clabe:
type: string
agreement:
type: string
name:
type: string
RefundRequest:
type: object
properties:
description:
type: string
amount:
type: number
format: float
description: Optional partial refund amount.
CaptureRequest:
type: object
properties:
amount:
type: number
format: float
description: Amount to capture, up to the authorized amount.
CreateCustomer:
type: object
required:
- name
- email
properties:
name:
type: string
last_name:
type: string
email:
type: string
phone_number:
type: string
requires_account:
type: boolean
description: Whether the customer requires an Openpay balance account.
address:
$ref: '#/components/schemas/Address'
Customer:
type: object
properties:
id:
type: string
name:
type: string
last_name:
type: string
email:
type: string
phone_number:
type: string
status:
type: string
balance:
type: number
format: float
creation_date:
type: string
format: date-time
address:
$ref: '#/components/schemas/Address'
Address:
type: object
properties:
line1:
type: string
line2:
type: string
line3:
type: string
postal_code:
type: string
state:
type: string
city:
type: string
country_code:
type: string
example: MX
CreateCard:
type: object
properties:
card_number:
type: string
holder_name:
type: string
expiration_year:
type: string
expiration_month:
type: string
cvv2:
type: string
device_session_id:
type: string
token_id:
type: string
description: Provide a token id instead of raw card data.
Card:
type: object
properties:
id:
type: string
type:
type: string
enum:
- debit
- credit
brand:
type: string
example: visa
card_number:
type: string
description: Masked card number.
holder_name:
type: string
expiration_year:
type: string
expiration_month:
type: string
bank_name:
type: string
bank_code:
type: string
creation_date:
type: string
format: date-time
CreateToken:
type: object
required:
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openpay/refs/heads/main/openapi/openpay-openapi.yml