magpie-mcp-server
Version:
Model Context Protocol server for Magpie Payment Platform APIs. Enables AI agents to process payments, create checkout sessions, manage payment requests, and handle payment links.
724 lines (723 loc) • 26 kB
YAML
openapi: 3.0.2
info:
title: Magpie Checkout API
description: The Magpie Checkout API allows you to create and manage Checkout Sessions. A Checkout Session represents a customer's session as they pay for one or more items.
version: 1.0.0
servers:
- url: https://api.pay.magpie.im/
description: Production server for Magpie Checkout API
paths:
/:
post:
tags:
- Checkout Sessions
summary: Create a Session
description: Creates a sessions object
operationId: create-session
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSessionSerializer'
examples:
payment:
summary: Payment mode
description: Use this when you want to collect one-time payments
value:
currency: php
cancel_url: https://example.com/cancel
line_items:
- name: Magpie Tumbler
quantity: 1
amount: 5000
mode: payment
payment_method_types:
- card
- bpi
- gcash
- maya
- alipay
- unionpay
- wechat
success_url: https://example.com/success
setup:
summary: Setup mode
description: Use this to authorize a payment and capture it later. Only works with card payments.
value:
currency: php
cancel_url: https://example.com/cancel
line_items:
- name: Magpie Tumbler
quantity: 1
amount: 5000
mode: setup
payment_method_types:
- card
success_url: https://example.com/success
subscription:
summary: Subscription mode
description: Use this to collect payment information from your customer to charge them later for recurring payments. Only works on card payments.
value:
currency: php
cancel_url: https://example.com/cancel
line_items:
- name: Magpie Tumbler
quantity: 1
amount: 5000
mode: subscription
payment_method_types:
- card
success_url: https://example.com/success
save_card:
summary: Save card mode
description: Use this to collect and save a card information to a customer, also know as card vaulting. Only works on card payments.
value:
currency: php
cancel_url: https://example.com/cancel
mode: save_card
payment_method_types:
- card
success_url: https://example.com/success
required: true
example:
currency: php
cancel_url: https://example.com/cancel
line_items:
- name: Magpie Tumbler
quantity: 1
amount: 5000
mode: payment
payment_method_types:
- card
- bpi
- gcash
- maya
- alipay
- unionpay
- wechat
success_url: https://example.com/success
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/ReadSessionSerializer'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBasic: []
get:
tags:
- Checkout Sessions
summary: List all Checkout Sessions
description: Returns a list of Checkouts Sessions
operationId: list-sessions
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ListSessionsSerializer'
security:
- HTTPBasic: []
/{id}:
get:
tags:
- Checkout Sessions
summary: Retrieve a Session
description: Retrieves a Session object
operationId: retrieve-session
parameters:
- name: id
in: path
description: The ID of the Checkout Session to retrieve
required: true
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ReadSessionSerializer'
'404':
description: Session not found
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPNotFoundError'
security:
- HTTPBasic: []
/{id}/expire:
post:
tags:
- Checkout Sessions
summary: Expire a Session
description: A Session can be expired when it has a status of unpaid. After a Session expires, a customer can't complete or pay a Session and customers loading the Session should see a message saying the Session is expired.
operationId: expire-session
parameters:
- name: id
in: path
description: The ID of the Checkout Session to expire
required: true
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ReadSessionSerializer'
'404':
description: Session not found
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPNotFoundError'
security:
- HTTPBasic: []
/{id}/capture:
post:
tags:
- Checkout Sessions
summary: Capture a Session
description: A Session can be captured when it has a status of `authorized`. After a Session is captured, the payment is processed and the Session is marked as paid.
operationId: capture-session
parameters:
- name: id
in: path
description: The ID of the Checkout Session to capture
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
amount:
title: Amount
description: The amount to capture, which must be less than or equal to the authorized amount. If not provided, will capture the full authorized amount.
type: integer
example: 5000
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ReadSessionSerializer'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'404':
description: Session not found
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPNotFoundError'
security:
- HTTPBasic: []
components:
schemas:
AddressSerializer:
title: Address
description: Address information collected from the customer.
properties:
name:
description: Customer name
type: string
example: Gerry Isaac
line1:
description: Address line 1 (e.g., house number, street, or company name).
type: string
example: '#123 JP Rizal St.'
line2:
description: Address line 2 (e.g., apartment, suite, or building).
type: string
barangay:
description: Suburb, town, village, or district.
type: string
example: San Antonio
city:
description: City or municipality.
type: string
example: Makati City
state:
description: State, county, province, or region.
type: string
example: Metro Manila
postal_code:
description: ZIP or postal code.
type: string
example: 1200
country:
description: Two-letter ISO country code.
type: string
example: PH
BrandingType:
title: Branding
description: Details on branding elements to apply when rendering this Checkout Session.
type: object
properties:
icon:
description: A secure URL to an image icon
type: string
nullable: true
example: https://example.com/icon.png
logo:
description: A secure URL to an image logo
type: string
nullable: true
example: https://example.com/logo.png
use_logo:
description: Has the value of true if logo should be rendered in payment page or false if icon should be used.
type: boolean
example: true
primary_color:
description: A hex color code that will be used as background color of the payment page
type: string
nullable: true
example: '#FFFFFF'
secondary_color:
description: A hex color code that will be used as background color of the submit or PAY button
type: string
nullable: true
example: '#4f99fe'
BillingAddressCollection:
title: BillingAddressCollection
description: Describes whether Checkout should collect the customer's billing address.
type: string
enum:
- auto
- required
default: auto
example: required
CreateSessionSerializer:
title: CreateSessionSerializer
required:
- cancel_url
- currency
- line_items
- payment_method_types
- success_url
properties:
bank_code:
description: A custom code provided by a bank you want to use for online banking payment methods
type: string
example: null
branding:
allOf:
- $ref: '#/components/schemas/BrandingType'
billing_address_collection:
allOf:
- $ref: '#/components/schemas/BillingAddressCollection'
cancel_url:
description: Customers will be directed to this URL if they decide to cancel payment and return to your website.
type: string
example: https://example.com/cancel
client_reference_id:
description: A unique string to reference the Checkout Session. This can be a customer ID, a card ID, or similar, and can be used to reconcile the Session with your internal systems.
type: string
example: null
currency:
description: Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a supported currency.
type: string
example: php
customer:
description: The ID of an existing `customer` that will be associated with this Checkout Session. This is used to prefill the customer-related fields like email address, name and phone on the payment page.
type: string
example: cus_ktDqQST3lm91sZ7y
customer_email:
description: Email address of customer. This is used to prefill the email field on the payment page.
type: string
example: jerry.isaac@email.com
customer_name:
description: Name of customer. This is used to prefill the name field on the payment page.
type: string
example: Gerry Isaac
customer_name_collection:
description: Describes whether Checkout should collect the customer's name.
type: boolean
example: true
customer_phone:
description: Phone number of customer. This is used to prefill the phone field on the payment page.
type: string
example: '+639123456789'
description:
description: If provided, Checkout will use this value as description of the `charge`.
type: string
example: Purchase of Magpie Tumbler
line_items:
title: LineItem[]
description: A list of items the customer is purchasing. Each item is an object with the following properties.
type: array
items:
$ref: '#/components/schemas/LineItemSerializer'
locale:
description: The IETF language tag of the locale Checkout is displayed in. Defaults to `en`. As of current version, Checkout will not yet support other locales.
type: string
enum:
- en
example: en
metadata:
description: A set of key-value pairs that you can attach to a Checkout Session object. It can be useful for storing additional information about the session in a structured format.
type: object
additionalProperties:
type: string
example: { 'PO Number': '123456' }
mode:
description: The mode of the Checkout Session. Required when creating a Checkout Session.
type: string
enum:
- payment
- setup
- subscription
- save_card
example: payment
payment_method_types:
description: A list of the types of payment methods (e.g., `card`) this Checkout Session can accept.
type: array
items:
$ref: '#/components/schemas/PaymentMethodType'
example:
- card
- bpi
- gcash
- maya
- alipay
- unionpay
- wechat
phone_number_collection:
description: Describes whether Checkout should collect the customer's phone number.
type: boolean
example: true
shipping_address_collection:
allOf:
- $ref: '#/components/schemas/ShippingAddressCollection'
submit_type:
description: Describes the type of transaction being performed by Checkout in order to customize relevant text on the page, such as the submit button. `submit_type` can only be specified on Checkout Session in `payment` mode, but not on other modes.
type: string
enum:
- pay
- book
- donate
- send
example: pay
success_url:
description: Customers will be directed to this URL after a successful payment.
type: string
example: https://example.com/success
HTTPNotFoundError:
title: HTTPNotFoundError
type: object
properties:
message:
title: Error message
type: string
example: Session id does not exist
HTTPValidationError:
title: HTTPValidationError
type: object
properties:
message:
title: Error message
type: array
items:
type: string
example: ['currency is required']
error:
title: Error type
type: string
example: Bad Request
statusCode:
title: Error code
type: integer
example: 400
LineItemSerializer:
title: LineItem
description: A list of items the customer is purchasing. Required unless `save_card` mode.
type: object
required:
- amount
- name
- quantity
properties:
amount:
description: Unit amount of the product in cents represented as a whole integer.
type: integer
example: 5000
description:
description: A description of the product
type: string
nullable: true
image:
description: A secure URL to an image of the product
type: string
nullable: true
name:
description: The name of the product
type: string
quantity:
description: The quantity of the products being purchased
type: integer
example: 1
minimum: 0
ListSessionsSerializer:
title: ListSessionsSerializer
type: array
items:
$ref: '#/components/schemas/ReadSessionSerializer'
Merchant:
description: Contains the merchant details that created this Checkout Session
properties:
name:
description: Name of the merchant
type: string
example: Magpie Shop
support_email:
description: Email address of the merchant's support team
type: string
nullable: true
example: support@merchant.com
support_phone:
description: Phone number of the merchant's support team
type: string
nullable: true
example: null
PaymentMethodType:
title: PaymentMethod
description: The payment method types that the Checkout Session is allowed to use. `gcash` payment method requires additional approval.
type: string
enum:
- card
- bpi
- gcash
- maya
- alipay
- unionpay
- wechat
PaymentStatusType:
description: The payment status of the Checkout Session. Use this value to decide when to fulfill your customer's order.
type: string
enum:
- paid
- unpaid
- authorized
- expired
example: unpaid
ReadSessionSerializer:
title: ReadSessionSerializer
properties:
id:
description: Unique identifier for the Session object.
type: string
example: cs_ktDqQST3lm91sZ7y
object:
description: String representing the object's type. Objects of the same type share the same value.
type: string
value: checkout.session
amount_subtotal:
description: Total of all items before discounts or taxes are applied. Amount in cents represented as whole integer.
type: integer
example: 5000
amount_total:
description: Total of all items after discounts and taxes are applied. Amount in cents represented as whole integer.
type: integer
example: 5000
bank_code:
description: A custom code provided by a bank you want to use for online banking payment methods
type: string
nullable: true
example: null
branding:
allOf:
- $ref: '#/components/schemas/BrandingType'
billing:
description: The customer's billing address.
nullable: true
allOf:
- $ref: '#/components/schemas/AddressSerializer'
billing_address_collection:
title: ''
allOf:
- $ref: '#/components/schemas/BillingAddressCollection'
cancel_url:
description: The URL the customer will be directed to if they decide to cancel payment and return to your website.
type: string
example: https://example.com/cancel
client_reference_id:
description: A unique string to reference the Checkout Session. This can be a customer ID, a card ID, or similar, and can be used to reconcile the Session with your internal systems.
type: string
example: null
created_at:
description: The date and time the Checkout Session was created.
type: string
format: date-time
example: 2021-09-01T08:00:00Z
currency:
description: Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a supported currency.
type: string
example: php
customer:
description: The ID of an existing customer that will be associated with this Checkout Session.
type: string
example: cus_ktDqQST3lm91sZ7y
customer_email:
description: Email address of customer.
type: string
example: gerry.isaac@email.com
customer_name:
description: Name of customer.
type: string
example: Gerry Isaac
customer_name_collection:
description: Describes whether Checkout should collect the customer's name.
type: boolean
example: true
customer_phone:
description: Phone number of customer.
type: string
example: '+639123456789'
description:
description: If provided, Checkout will use this value as description of the `charge`.
type: string
example: Purchase of Magpie Tumbler
expires_at:
description: The date and time the Checkout Session will expire.
type: string
format: date-time
example: 2021-09-02T08:00:00Z
last_updated:
description: The date and time the Checkout Session was last updated.
type: string
format: date-time
example: 2021-09-01T08:00:00Z
line_items:
title: LineItem[]
description: The line items purchased by the customer.
type: array
items:
$ref: '#/components/schemas/LineItemSerializer'
example:
- name: Magpie Tumbler
quantity: 1
amount: 5000
livemode:
description: Has the value of `true` if the object exists in live mode or the value of `false` if the object exists in test mode.
type: boolean
example: true
locale:
description: The IETF language tag of the locale Checkout is displayed in.
type: string
enum:
- en
example: en
merchant:
description: Contains the merchant details that created this Checkout Session
allOf:
- $ref: '#/components/schemas/Merchant'
metadata:
description: A set of key-value pairs that you can attach to a Checkout Session object.
type: object
additionalProperties:
type: string
example:
'PO Number': '123456'
mode:
description: The mode of the Checkout Session.
type: string
enum:
- payment
# - setup
# - subscription
# - save_card
default: payment
example: payment
payment_details:
description: The `charge` object details associated with the Checkout Session after successful payment.
type: object
nullable: true
example: null
payment_method_types:
description: A list of the types of payment methods (e.g. card) this Checkout Session is allowed to accept.
type: array
items:
$ref: '#/components/schemas/PaymentMethodType'
example:
- card
- bpi
- gcash
- maya
payment_status:
- $ref: '#/components/schemas/PaymentStatusType'
payment_url:
description: The URL to the Checkout Session. Redirect customers to this URL to take them to Checkout.
type: string
example: https://new.pay.magpie.im/cs_NQrmHLLhioV34BUG
phone_number_collection:
description: Describes whether Checkout should collect the customer's phone number.
type: boolean
example: true
require_auth:
title: Require auth
description: Indicates whether 3D Secure authentication shall be required for card payments. Always have a value `true`.
type: boolean
example: true
shipping:
title: Shipping address
description: The customer's shipping address.
nullable: true
allOf:
- $ref: '#/components/schemas/AddressSerializer'
shipping_address_collection:
title: ShippingAddressCollection
allOf:
- $ref: '#/components/schemas/ShippingAddressCollection'
submit_type:
description: Describes the type of transaction being performed by Checkout in order to customize relevant text on the page, such as the submit button.
type: string
enum:
- pay
- book
- donate
- send
example: pay
success_url:
description: The URL the customer will be directed to after a successful payment.
type: string
example: https://example.com/success
ShippingAddressCollection:
title: ShippingAddressCollection
description: Describes whether Checkout should collect the customer's shipping address.
type: object
required:
- allowed_countries
properties:
allowed_countries:
title: Allowed countries
description: A list of two-letter ISO country codes. Checkout will only collect shipping address from customers in these countries.
type: array
items:
type: string
example:
- PH
- SG
securitySchemes:
HTTPBasic:
type: http
scheme: basic