Configure HTTPS endpoints that receive signed event notifications for cards, users, transactions, and adjustments, validated with the x-endpoint, x-signature, and timestamp headers.
openapi: 3.0.1
info:
title: Pomelo API
description: >-
REST API for Pomelo (pomelo.la), the Latin American card-issuing and
embedded-finance platform. Covers user onboarding and identity verification
(KYC/KYB), card issuing and lifecycle management, card accounts and balances,
transaction processing and history, transfers and settlements, and the
real-time authorizer plus event webhooks. Authentication uses the OAuth 2.0
client-credentials grant; the issued JWT is sent as a Bearer token on every
request.
termsOfService: https://www.pomelo.la
contact:
name: Pomelo Developers
url: https://developers.pomelo.la
version: '1.0'
servers:
- url: https://api.pomelo.la
description: Pomelo production API
- url: https://auth.pomelo.la
description: Pomelo OAuth 2.0 token issuer
security:
- bearerAuth: []
tags:
- name: Authentication
description: OAuth 2.0 client-credentials token issuance.
- name: Users
description: Cardholder records and KYC/KYB identity verification.
- name: Cards
description: Issuing and lifecycle of physical and virtual cards.
- name: Card Accounts
description: Card account balances, activities, and movements.
- name: Transactions
description: Processed transactions, summaries, and history.
- name: Transfers
description: Money movement and settlements across card accounts.
- name: Authorizations
description: Real-time authorizer callback contract (client-implemented).
paths:
/oauth/token:
post:
operationId: createToken
tags:
- Authentication
summary: Obtain an OAuth 2.0 access token.
description: >-
Exchange client credentials for a Bearer access token (JWT) using the
client_credentials grant. Issued against https://auth.pomelo.la. The
same token is returned until it expires, after which a new one is issued.
servers:
- url: https://auth.pomelo.la
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TokenRequest'
responses:
'200':
description: A new or cached access token.
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/users/v1:
post:
operationId: createUser
tags:
- Users
summary: Create a user.
description: Register a new cardholder. An email uniquely identifies the user on the platform.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserRequest'
responses:
'201':
description: User created.
content:
application/json:
schema:
$ref: '#/components/schemas/UserEnvelope'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
get:
operationId: searchUsers
tags:
- Users
summary: Search users.
description: Query the user database by parameters such as identification, email, or status.
parameters:
- name: identification_value
in: query
schema:
type: string
- name: email
in: query
schema:
type: string
format: email
- name: status
in: query
schema:
$ref: '#/components/schemas/UserStatus'
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/PageNumber'
responses:
'200':
description: Matching users.
content:
application/json:
schema:
$ref: '#/components/schemas/UserList'
'401':
$ref: '#/components/responses/Unauthorized'
/users/v1/{id}:
parameters:
- $ref: '#/components/parameters/UserId'
get:
operationId: getUser
tags:
- Users
summary: Get a user.
responses:
'200':
description: The requested user.
content:
application/json:
schema:
$ref: '#/components/schemas/UserEnvelope'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: modifyUser
tags:
- Users
summary: Modify a user.
description: Update existing personal information for a user.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserPatch'
responses:
'200':
description: Updated user.
content:
application/json:
schema:
$ref: '#/components/schemas/UserEnvelope'
'404':
$ref: '#/components/responses/NotFound'
/cards/v1:
post:
operationId: createCard
tags:
- Cards
summary: Create a card.
description: >-
Create a new nominated card, which can be physical or virtual, for a user.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CardRequest'
responses:
'201':
description: Card created.
content:
application/json:
schema:
$ref: '#/components/schemas/CardEnvelope'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
get:
operationId: searchCards
tags:
- Cards
summary: Search cards.
parameters:
- name: user_id
in: query
schema:
type: string
- name: status
in: query
schema:
$ref: '#/components/schemas/CardStatus'
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/PageNumber'
responses:
'200':
description: Matching cards.
content:
application/json:
schema:
$ref: '#/components/schemas/CardList'
/cards/v1/{id}:
parameters:
- $ref: '#/components/parameters/CardId'
get:
operationId: getCard
tags:
- Cards
summary: Get a card.
responses:
'200':
description: The requested card.
content:
application/json:
schema:
$ref: '#/components/schemas/CardEnvelope'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: updateCard
tags:
- Cards
summary: Update a card.
description: Update the status, affinity group, or PIN of a card.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CardPatch'
responses:
'200':
description: Updated card.
content:
application/json:
schema:
$ref: '#/components/schemas/CardEnvelope'
'404':
$ref: '#/components/responses/NotFound'
/cards/v1/activation:
post:
operationId: activateCard
tags:
- Cards
summary: Activate a physical card.
description: Activate a physical card and optionally set its PIN.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CardActivationRequest'
responses:
'200':
description: Card activated.
content:
application/json:
schema:
$ref: '#/components/schemas/CardEnvelope'
'400':
$ref: '#/components/responses/BadRequest'
/cards/v1/batches:
post:
operationId: createCardBatch
tags:
- Cards
summary: Create a batch of innominated cards.
description: Create a batch of innominated cards (maximum 1,000 cards per batch).
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CardBatchRequest'
responses:
'201':
description: Batch created.
content:
application/json:
schema:
$ref: '#/components/schemas/CardBatchEnvelope'
/cards/v1/{id}/shipment:
parameters:
- $ref: '#/components/parameters/CardId'
patch:
operationId: updateCardShipment
tags:
- Cards
summary: Update a card shipment address.
description: >-
Update the shipping address of a card. The card must be a physical
nominated card with status CREATED.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ShipmentRequest'
responses:
'200':
description: Shipment updated.
content:
application/json:
schema:
$ref: '#/components/schemas/CardEnvelope'
/accounts/v1:
get:
operationId: searchCardAccounts
tags:
- Card Accounts
summary: Search card accounts.
parameters:
- name: user_id
in: query
schema:
type: string
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/PageNumber'
responses:
'200':
description: Matching card accounts.
content:
application/json:
schema:
$ref: '#/components/schemas/CardAccountList'
/accounts/v1/{id}:
parameters:
- $ref: '#/components/parameters/AccountId'
get:
operationId: getCardAccount
tags:
- Card Accounts
summary: Get a card account.
responses:
'200':
description: The requested card account.
content:
application/json:
schema:
$ref: '#/components/schemas/CardAccountEnvelope'
'404':
$ref: '#/components/responses/NotFound'
/accounts/v1/{id}/movements:
parameters:
- $ref: '#/components/parameters/AccountId'
get:
operationId: listAccountMovements
tags:
- Card Accounts
summary: List account movements.
description: List the balance movements and activities for a card account.
parameters:
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/PageNumber'
responses:
'200':
description: Movements for the account.
content:
application/json:
schema:
$ref: '#/components/schemas/MovementList'
/transactions/v1:
get:
operationId: searchTransactions
tags:
- Transactions
summary: Search transactions.
description: Search processed card transactions by user, card, date range, or status.
parameters:
- name: user_id
in: query
schema:
type: string
- name: card_id
in: query
schema:
type: string
- name: status
in: query
schema:
$ref: '#/components/schemas/TransactionStatus'
- name: from
in: query
schema:
type: string
format: date-time
- name: to
in: query
schema:
type: string
format: date-time
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/PageNumber'
responses:
'200':
description: Matching transactions.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionList'
/transactions/v1/{id}:
parameters:
- name: id
in: path
required: true
schema:
type: string
get:
operationId: getTransaction
tags:
- Transactions
summary: Get a transaction.
responses:
'200':
description: The requested transaction.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionEnvelope'
'404':
$ref: '#/components/responses/NotFound'
/transfers/v1:
post:
operationId: createTransfer
tags:
- Transfers
summary: Create a transfer.
description: Move funds between card accounts to fund or reconcile the program.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TransferRequest'
responses:
'201':
description: Transfer created.
content:
application/json:
schema:
$ref: '#/components/schemas/TransferEnvelope'
'400':
$ref: '#/components/responses/BadRequest'
get:
operationId: searchTransfers
tags:
- Transfers
summary: Search transfers.
parameters:
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/PageNumber'
responses:
'200':
description: Matching transfers.
content:
application/json:
schema:
$ref: '#/components/schemas/TransferList'
/transfers/v1/{id}:
parameters:
- name: id
in: path
required: true
schema:
type: string
get:
operationId: getTransfer
tags:
- Transfers
summary: Get a transfer.
responses:
'200':
description: The requested transfer.
content:
application/json:
schema:
$ref: '#/components/schemas/TransferEnvelope'
'404':
$ref: '#/components/responses/NotFound'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: OAuth 2.0 client-credentials access token issued by /oauth/token.
oauth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://auth.pomelo.la/oauth/token
scopes: {}
parameters:
UserId:
name: id
in: path
required: true
schema:
type: string
CardId:
name: id
in: path
required: true
schema:
type: string
AccountId:
name: id
in: path
required: true
schema:
type: string
PageSize:
name: page[size]
in: query
schema:
type: integer
default: 25
PageNumber:
name: page[number]
in: query
schema:
type: integer
default: 0
responses:
BadRequest:
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Missing or invalid Bearer token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
TokenRequest:
type: object
required:
- client_id
- client_secret
- audience
- grant_type
properties:
client_id:
type: string
client_secret:
type: string
audience:
type: string
example: https://api.pomelo.la
grant_type:
type: string
enum:
- client_credentials
TokenResponse:
type: object
properties:
access_token:
type: string
description: JWT Bearer token.
scope:
type: string
expires_in:
type: integer
example: 86400
token_type:
type: string
example: Bearer
Error:
type: object
properties:
error:
type: object
properties:
details:
type: array
items:
type: object
properties:
code:
type: string
detail:
type: string
UserStatus:
type: string
enum:
- ACTIVE
- BLOCKED
- DISABLED
Address:
type: object
properties:
street_name:
type: string
street_number:
type: string
zip_code:
type: string
city:
type: string
region:
type: string
country:
type: string
description: ISO 3166-1 alpha-3 country code.
UserRequest:
type: object
required:
- name
- surname
- email
- operation_country
properties:
name:
type: string
surname:
type: string
identification_type:
type: string
example: DNI
identification_value:
type: string
birthdate:
type: string
format: date
gender:
type: string
enum:
- MALE
- FEMALE
- OTHER
email:
type: string
format: email
phone:
type: string
legal_address:
$ref: '#/components/schemas/Address'
operation_country:
type: string
description: ISO 3166-1 alpha-3 operating country (e.g. ARG, BRA, MEX).
UserPatch:
type: object
properties:
email:
type: string
format: email
phone:
type: string
legal_address:
$ref: '#/components/schemas/Address'
status:
$ref: '#/components/schemas/UserStatus'
User:
allOf:
- $ref: '#/components/schemas/UserRequest'
- type: object
properties:
id:
type: string
status:
$ref: '#/components/schemas/UserStatus'
created_at:
type: string
format: date-time
UserEnvelope:
type: object
properties:
data:
$ref: '#/components/schemas/User'
UserList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
meta:
$ref: '#/components/schemas/PageMeta'
CardStatus:
type: string
enum:
- CREATED
- ACTIVE
- BLOCKED
- DISABLED
- EMERGENCY
CardRequest:
type: object
required:
- user_id
- card_type
properties:
user_id:
type: string
affinity_group_id:
type: string
card_type:
type: string
enum:
- PHYSICAL
- VIRTUAL
previous_card_id:
type: string
address:
$ref: '#/components/schemas/Address'
CardPatch:
type: object
properties:
status:
$ref: '#/components/schemas/CardStatus'
status_reason:
type: string
example: CLIENT_INTERNAL_REASON
affinity_group_id:
type: string
pin:
type: string
CardActivationRequest:
type: object
required:
- card_id
properties:
card_id:
type: string
pin:
type: string
CardBatchRequest:
type: object
required:
- affinity_group_id
- quantity
properties:
affinity_group_id:
type: string
card_type:
type: string
enum:
- PHYSICAL
- VIRTUAL
quantity:
type: integer
maximum: 1000
ShipmentRequest:
type: object
properties:
address:
$ref: '#/components/schemas/Address'
external_tracking_id:
type: string
Card:
type: object
properties:
id:
type: string
user_id:
type: string
affinity_group_id:
type: string
card_type:
type: string
enum:
- PHYSICAL
- VIRTUAL
product_type:
type: string
enum:
- PREPAID
- DEBIT
- CREDIT
status:
$ref: '#/components/schemas/CardStatus'
status_detail:
type: string
shipment_id:
type: string
last_four:
type: string
provider:
type: string
enum:
- MASTERCARD
- VISA
start_date:
type: string
format: date
CardEnvelope:
type: object
properties:
data:
$ref: '#/components/schemas/Card'
CardList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Card'
meta:
$ref: '#/components/schemas/PageMeta'
CardBatchEnvelope:
type: object
properties:
data:
type: object
properties:
batch_id:
type: string
quantity:
type: integer
status:
type: string
CardAccount:
type: object
properties:
id:
type: string
user_id:
type: string
balance:
type: number
format: double
currency:
type: string
description: ISO 4217 currency code.
status:
type: string
CardAccountEnvelope:
type: object
properties:
data:
$ref: '#/components/schemas/CardAccount'
CardAccountList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/CardAccount'
meta:
$ref: '#/components/schemas/PageMeta'
Movement:
type: object
properties:
id:
type: string
account_id:
type: string
type:
type: string
enum:
- CREDIT
- DEBIT
amount:
type: number
format: double
currency:
type: string
created_at:
type: string
format: date-time
MovementList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Movement'
meta:
$ref: '#/components/schemas/PageMeta'
TransactionStatus:
type: string
enum:
- APPROVED
- REJECTED
- REVERSED
Amount:
type: object
properties:
total:
type: number
format: double
currency:
type: string
details:
type: array
items:
type: object
properties:
type:
type: string
amount:
type: number
format: double
currency:
type: string
Merchant:
type: object
properties:
id:
type: string
name:
type: string
mcc:
type: string
country:
type: string
Transaction:
type: object
properties:
id:
type: string
country_code:
type: string
type:
type: string
enum:
- PURCHASE
- WITHDRAWAL
- EXTRACASH
- BALANCE_INQUIRY
- REFUND
- PAYMENT
- REVERSAL
- ADJUSTMENT
point_type:
type: string
enum:
- POS
- ECOMMERCE
- ATM
- MOTO
entry_mode:
type: string
enum:
- MANUAL
- CHIP
- CONTACTLESS
- CREDENTIAL_ON_FILE
- OTHER
origin:
type: string
enum:
- DOMESTIC
- INTERNATIONAL
source:
type: string
enum:
- DOMESTIC
- INTERNATIONAL
local_date_time:
type: string
format: date-time
original_transaction_id:
type: string
user_id:
type: string
card_id:
type: string
amount:
$ref: '#/components/schemas/Amount'
merchant:
$ref: '#/components/schemas/Merchant'
status:
$ref: '#/components/schemas/TransactionStatus'
status_detail:
type: string
TransactionEnvelope:
type: object
properties:
data:
$ref: '#/components/schemas/Transaction'
TransactionList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Transaction'
meta:
$ref: '#/components/schemas/PageMeta'
TransferRequest:
type: object
required:
- origin_account_id
- destination_account_id
- amount
properties:
origin_account_id:
type: string
destination_account_id:
type: string
amount:
type: number
format: double
currency:
type: string
description:
type: string
Transfer:
type: object
properties:
id:
type: string
origin_account_id:
type: string
destination_account_id:
type: string
amount:
type: number
format: double
currency:
type: string
status:
type: string
enum:
- PENDING
- COMPLETED
- REJECTED
created_at:
type: string
format: date-time
TransferEnvelope:
type: object
properties:
data:
$ref: '#/components/schemas/Transfer'
TransferList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Transfer'
meta:
$ref: '#/components/schemas/PageMeta'
PageMeta:
type: object
properties:
pagination:
type: object
properties:
page_size:
type: integer
page_number:
type: integer
total_pages:
type: integer
total_elements:
type: integer