PayMongo Forex API
Locks in a price for converting between the Philippine Peso and supported foreign currencies via Rates and Quotes, settled across the platform.
OpenAPI Specification
# Provenance: modeled-from-docs. PayMongo does not publish a downloadable
# first-party OpenAPI document. This specification was hand-modeled from the
# official developer documentation at https://docs.paymongo.com (API Reference,
# formerly developers.paymongo.com which now 301-redirects to docs.paymongo.com)
# and the machine-readable index at https://docs.paymongo.com/llms.txt.
# Verified live: GET https://api.paymongo.com/v1/payment_intents -> 401 (Basic auth required).
# Base URL, Basic-auth scheme (public key = username, secret key = password),
# PHP-only currency, and amount-in-centavos were confirmed against the docs on 2026-07-17.
openapi: 3.0.3
info:
title: PayMongo API
description: >-
PayMongo is a Philippine payments platform. The REST API lets businesses
accept payments via cards, GCash, Maya (PayMaya), GrabPay, ShopeePay,
QR Ph, BillEase (buy-now-pay-later), and direct online banking, using the
Payment Intent / Payment Method workflow, hosted Checkout Sessions,
Payment Links, Customers, Refunds, and Webhooks. All amounts are integers
in centavos (1 PHP = 100). PHP is the only settlement currency (card
intents may optionally be switched to USD).
version: '2020-08-08'
termsOfService: https://www.paymongo.com/terms
contact:
name: PayMongo Developer Support
email: support@paymongo.com
url: https://docs.paymongo.com
servers:
- url: https://api.paymongo.com/v1
description: Production (live and test mode selected by API key prefix)
security:
- basicAuth: []
tags:
- name: Payment Intents
- name: Payment Methods
- name: Payments
- name: Sources
- name: Checkout Sessions
- name: Payment Links
- name: Customers
- name: Refunds
- name: Webhooks
- name: QR Ph
paths:
/payment_intents:
post:
operationId: createPaymentIntent
tags: [Payment Intents]
summary: Create a Payment Intent
description: >-
Creates a Payment Intent that tracks the lifecycle of a payment. Uses
the secret API key. Amount is an integer in centavos (minimum 2000 =
PHP 20.00 for most methods).
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentIntentCreate'
responses:
'200':
description: Payment Intent created
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentIntentResource'
'400': { $ref: '#/components/responses/Error' }
'401': { $ref: '#/components/responses/Error' }
/payment_intents/{id}:
get:
operationId: retrievePaymentIntent
tags: [Payment Intents]
summary: Retrieve a Payment Intent
parameters:
- $ref: '#/components/parameters/ResourceId'
- name: client_key
in: query
required: false
schema: { type: string }
description: Client key allowing retrieval with the public key (client-side).
responses:
'200':
description: Payment Intent
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentIntentResource'
'404': { $ref: '#/components/responses/Error' }
/payment_intents/{id}/attach:
post:
operationId: attachPaymentIntent
tags: [Payment Intents]
summary: Attach a Payment Method to a Payment Intent
description: >-
Attaches a Payment Method to a Payment Intent to attempt the payment.
For redirect-based methods (GCash, GrabPay, Maya) the response contains
a next_action.redirect.url the customer must be sent to.
parameters:
- $ref: '#/components/parameters/ResourceId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentIntentAttach'
responses:
'200':
description: Payment Intent after attach
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentIntentResource'
'400': { $ref: '#/components/responses/Error' }
/payment_methods:
post:
operationId: createPaymentMethod
tags: [Payment Methods]
summary: Create a Payment Method
description: >-
Creates a Payment Method describing how the customer pays (card, gcash,
grab_pay, paymaya, billease, dob, qrph). May be created with the public
or secret API key.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentMethodCreate'
responses:
'200':
description: Payment Method created
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentMethodResource'
'400': { $ref: '#/components/responses/Error' }
/payment_methods/{id}:
get:
operationId: retrievePaymentMethod
tags: [Payment Methods]
summary: Retrieve a Payment Method
parameters:
- $ref: '#/components/parameters/ResourceId'
responses:
'200':
description: Payment Method
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentMethodResource'
'404': { $ref: '#/components/responses/Error' }
/payments:
get:
operationId: listPayments
tags: [Payments]
summary: List all Payments
parameters:
- name: limit
in: query
schema: { type: integer, default: 10, maximum: 100 }
- name: before
in: query
schema: { type: string }
- name: after
in: query
schema: { type: string }
responses:
'200':
description: A list of Payment resources
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentList'
/payments/{id}:
get:
operationId: retrievePayment
tags: [Payments]
summary: Retrieve a Payment
parameters:
- $ref: '#/components/parameters/ResourceId'
responses:
'200':
description: Payment
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentResource'
'404': { $ref: '#/components/responses/Error' }
/sources:
post:
operationId: createSource
tags: [Sources]
summary: Create a Source (legacy GCash / GrabPay workflow)
description: >-
Legacy Sources workflow for GCash and GrabPay. Generates a redirect
checkout_url the customer authorizes. PayMongo recommends migrating to
the Payment Intent workflow.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SourceCreate'
responses:
'200':
description: Source created
content:
application/json:
schema:
$ref: '#/components/schemas/SourceResource'
'400': { $ref: '#/components/responses/Error' }
/sources/{id}:
get:
operationId: retrieveSource
tags: [Sources]
summary: Retrieve a Source
parameters:
- $ref: '#/components/parameters/ResourceId'
responses:
'200':
description: Source
content:
application/json:
schema:
$ref: '#/components/schemas/SourceResource'
'404': { $ref: '#/components/responses/Error' }
/checkout_sessions:
post:
operationId: createCheckoutSession
tags: [Checkout Sessions]
summary: Create a Checkout Session (Hosted Checkout)
description: >-
Creates a PayMongo-hosted checkout page. Returns checkout_url to which
the customer is redirected.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutSessionCreate'
responses:
'200':
description: Checkout Session created
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResource'
'400': { $ref: '#/components/responses/Error' }
/checkout_sessions/{id}:
get:
operationId: retrieveCheckoutSession
tags: [Checkout Sessions]
summary: Retrieve a Checkout Session
parameters:
- $ref: '#/components/parameters/ResourceId'
responses:
'200':
description: Checkout Session
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResource'
'404': { $ref: '#/components/responses/Error' }
/checkout_sessions/{id}/expire:
post:
operationId: expireCheckoutSession
tags: [Checkout Sessions]
summary: Expire a Checkout Session
parameters:
- $ref: '#/components/parameters/ResourceId'
responses:
'200':
description: Checkout Session expired
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResource'
/links:
post:
operationId: createPaymentLink
tags: [Payment Links]
summary: Create a Payment Link
description: >-
Creates a shareable Payment Link. (The newer Payment Links surface is
also available under /payment_links.)
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentLinkCreate'
responses:
'200':
description: Payment Link created
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResource'
'400': { $ref: '#/components/responses/Error' }
/links/{id}:
get:
operationId: retrievePaymentLink
tags: [Payment Links]
summary: Retrieve a Payment Link
parameters:
- $ref: '#/components/parameters/ResourceId'
responses:
'200':
description: Payment Link
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResource'
'404': { $ref: '#/components/responses/Error' }
/customers:
post:
operationId: createCustomer
tags: [Customers]
summary: Create a Customer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerCreate'
responses:
'200':
description: Customer created
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResource'
'400': { $ref: '#/components/responses/Error' }
get:
operationId: listCustomers
tags: [Customers]
summary: List Customers
responses:
'200':
description: A list of Customers
content:
application/json:
schema:
$ref: '#/components/schemas/GenericList'
/customers/{id}:
get:
operationId: retrieveCustomer
tags: [Customers]
summary: Retrieve a Customer
parameters:
- $ref: '#/components/parameters/ResourceId'
responses:
'200':
description: Customer
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResource'
'404': { $ref: '#/components/responses/Error' }
patch:
operationId: updateCustomer
tags: [Customers]
summary: Update a Customer
parameters:
- $ref: '#/components/parameters/ResourceId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerCreate'
responses:
'200':
description: Customer updated
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResource'
delete:
operationId: deleteCustomer
tags: [Customers]
summary: Delete a Customer
parameters:
- $ref: '#/components/parameters/ResourceId'
responses:
'200':
description: Customer deleted
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResource'
/refunds:
post:
operationId: createRefund
tags: [Refunds]
summary: Create a Refund
description: >-
Refunds all or part of a Payment. Amount is an integer in centavos;
reason is one of duplicate, fraudulent, requested_by_customer, others.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RefundCreate'
responses:
'200':
description: Refund created
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResource'
'400': { $ref: '#/components/responses/Error' }
get:
operationId: listRefunds
tags: [Refunds]
summary: List Refunds
responses:
'200':
description: A list of Refunds
content:
application/json:
schema:
$ref: '#/components/schemas/GenericList'
/refunds/{id}:
get:
operationId: retrieveRefund
tags: [Refunds]
summary: Retrieve a Refund
parameters:
- $ref: '#/components/parameters/ResourceId'
responses:
'200':
description: Refund
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResource'
'404': { $ref: '#/components/responses/Error' }
/qr_codes/static:
post:
operationId: createStaticQrPh
tags: [QR Ph]
summary: Create a static QR Ph code
description: Creates a reusable static QR Ph code for in-store acceptance.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GenericCreate'
responses:
'200':
description: Static QR Ph created
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResource'
'400': { $ref: '#/components/responses/Error' }
/webhooks:
post:
operationId: createWebhook
tags: [Webhooks]
summary: Create a Webhook
description: >-
Registers a webhook endpoint subscribed to event types. Deliveries are
signed HTTP POST callbacks (Paymongo-Signature header) - not a
WebSocket. Each webhook has a signing secret used to verify payloads.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookCreate'
responses:
'200':
description: Webhook created
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResource'
'400': { $ref: '#/components/responses/Error' }
get:
operationId: listWebhooks
tags: [Webhooks]
summary: List Webhooks
responses:
'200':
description: A list of Webhooks
content:
application/json:
schema:
$ref: '#/components/schemas/GenericList'
/webhooks/{id}:
get:
operationId: retrieveWebhook
tags: [Webhooks]
summary: Retrieve a Webhook
parameters:
- $ref: '#/components/parameters/ResourceId'
responses:
'200':
description: Webhook
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResource'
'404': { $ref: '#/components/responses/Error' }
/webhooks/{id}/enable:
post:
operationId: enableWebhook
tags: [Webhooks]
summary: Enable a Webhook
parameters:
- $ref: '#/components/parameters/ResourceId'
responses:
'200':
description: Webhook enabled
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResource'
/webhooks/{id}/disable:
post:
operationId: disableWebhook
tags: [Webhooks]
summary: Disable a Webhook
parameters:
- $ref: '#/components/parameters/ResourceId'
responses:
'200':
description: Webhook disabled
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResource'
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
HTTP Basic authentication. Provide your API key as the Basic-auth
username (secret key sk_test_* / sk_live_* for server-side calls;
for calls that accept the public key pk_test_* / pk_live_*, the public
key goes in the username field). The password field is left blank
unless a call requires both keys.
parameters:
ResourceId:
name: id
in: path
required: true
schema: { type: string }
description: The identifier of the resource (e.g. pi_..., pm_..., pay_...).
responses:
Error:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
schemas:
PaymentIntentCreate:
type: object
required: [data]
properties:
data:
type: object
properties:
attributes:
type: object
required: [amount, payment_method_allowed, currency]
properties:
amount:
type: integer
description: Amount in centavos (integer). Minimum typically 2000 (PHP 20.00).
example: 10000
currency:
type: string
description: Three-letter ISO currency code, uppercase. PHP is the default and only settlement currency (card intents may be switched to USD).
example: PHP
payment_method_allowed:
type: array
items:
type: string
enum: [card, gcash, grab_pay, paymaya, billease, dob, qrph]
example: [card, gcash, grab_pay, paymaya]
capture_type:
type: string
enum: [automatic, manual]
default: automatic
description:
type: string
statement_descriptor:
type: string
metadata:
type: object
additionalProperties: true
PaymentIntentAttach:
type: object
required: [data]
properties:
data:
type: object
properties:
attributes:
type: object
required: [payment_method]
properties:
payment_method:
type: string
description: The Payment Method id (pm_...) to attach.
client_key:
type: string
return_url:
type: string
description: URL the customer is redirected to after off-site authorization.
PaymentIntentResource:
type: object
properties:
data:
type: object
properties:
id: { type: string, example: pi_xxx }
type: { type: string, example: payment_intent }
attributes:
type: object
properties:
amount: { type: integer }
currency: { type: string }
status:
type: string
enum: [awaiting_payment_method, awaiting_next_action, processing, succeeded, cancelled]
client_key: { type: string }
next_action:
type: object
nullable: true
properties:
type: { type: string, example: redirect }
redirect:
type: object
properties:
url: { type: string }
return_url: { type: string }
PaymentMethodCreate:
type: object
required: [data]
properties:
data:
type: object
properties:
attributes:
type: object
required: [type]
properties:
type:
type: string
enum: [card, gcash, grab_pay, paymaya, billease, dob, qrph]
details:
type: object
description: Card details (number, exp_month, exp_year, cvc) when type=card.
properties:
card_number: { type: string }
exp_month: { type: integer }
exp_year: { type: integer }
cvc: { type: string }
billing:
type: object
properties:
name: { type: string }
email: { type: string }
phone: { type: string }
metadata:
type: object
additionalProperties: true
PaymentMethodResource:
type: object
properties:
data:
type: object
properties:
id: { type: string, example: pm_xxx }
type: { type: string, example: payment_method }
attributes:
type: object
properties:
type: { type: string }
billing: { type: object }
PaymentResource:
type: object
properties:
data:
type: object
properties:
id: { type: string, example: pay_xxx }
type: { type: string, example: payment }
attributes:
type: object
properties:
amount: { type: integer }
currency: { type: string }
fee: { type: integer }
net_amount: { type: integer }
status: { type: string, enum: [pending, paid, failed] }
source: { type: object }
PaymentList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/PaymentResource'
has_more: { type: boolean }
SourceCreate:
type: object
required: [data]
properties:
data:
type: object
properties:
attributes:
type: object
required: [amount, currency, type, redirect]
properties:
amount: { type: integer, description: Amount in centavos. }
currency: { type: string, example: PHP }
type:
type: string
enum: [gcash, grab_pay]
redirect:
type: object
required: [success, failed]
properties:
success: { type: string }
failed: { type: string }
SourceResource:
type: object
properties:
data:
type: object
properties:
id: { type: string, example: src_xxx }
type: { type: string, example: source }
attributes:
type: object
properties:
amount: { type: integer }
currency: { type: string }
status: { type: string, enum: [pending, chargeable, cancelled, expired, paid] }
type: { type: string }
redirect:
type: object
properties:
checkout_url: { type: string }
success: { type: string }
failed: { type: string }
CheckoutSessionCreate:
type: object
required: [data]
properties:
data:
type: object
properties:
attributes:
type: object
required: [line_items, payment_method_types]
properties:
line_items:
type: array
items:
type: object
properties:
name: { type: string }
quantity: { type: integer }
amount: { type: integer }
currency: { type: string, example: PHP }
payment_method_types:
type: array
items:
type: string
enum: [card, gcash, grab_pay, paymaya, billease, dob, qrph]
success_url: { type: string }
cancel_url: { type: string }
description: { type: string }
PaymentLinkCreate:
type: object
required: [data]
properties:
data:
type: object
properties:
attributes:
type: object
required: [amount, description]
properties:
amount: { type: integer, description: Amount in centavos. }
description: { type: string }
remarks: { type: string }
CustomerCreate:
type: object
required: [data]
properties:
data:
type: object
properties:
attributes:
type: object
required: [first_name, last_name, email, phone, default_device]
properties:
first_name: { type: string }
last_name: { type: string }
email: { type: string }
phone: { type: string }
default_device: { type: string, enum: [email, phone] }
RefundCreate:
type: object
required: [data]
properties:
data:
type: object
properties:
attributes:
type: object
required: [amount, payment_id, reason]
properties:
amount: { type: integer, description: Amount in centavos to refund. }
payment_id: { type: string, example: pay_xxx }
reason:
type: string
enum: [duplicate, fraudulent, requested_by_customer, others]
notes: { type: string }
WebhookCreate:
type: object
required: [data]
properties:
data:
type: object
properties:
attributes:
type: object
required: [url, events]
properties:
url: { type: string }
events:
type: array
items:
type: string
example: payment.paid
GenericCreate:
type: object
properties:
data:
type: object
properties:
attributes:
type: object
additionalProperties: true
GenericResource:
type: object
properties:
data:
type: object
properties:
id: { type: string }
type: { type: string }
attributes:
type: object
additionalProperties: true
GenericList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/GenericResource'
has_more: { type: boolean }
ErrorResponse:
type: object
properties:
errors:
type: array
items:
type: object
properties:
code: { type: string }
detail: { type: string }
source:
type: object
properties:
pointer: { type: string }
attribute: { type: string }