Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: gateway Purchases API
version: '1.0'
servers:
- url: https://gateway.pmnts-sandbox.io/v1.0
security:
- sec0: []
tags:
- name: Purchases
paths:
/purchases:
post:
summary: Create a purchase with fraud screening
description: ''
operationId: create-a-purchase-with-fraud-screening-1
parameters:
- name: Content-Type
in: header
description: application/json
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
required:
- amount
- reference
- customer_ip
- currency
- card_number
- card_holder
- card_expiry
properties:
amount:
type: integer
description: A positive integer representing how much to charge, in the smallest currency unit (eg., 100 to charge $1.00, or 100 to Charge ¥100, a zero decimal currency)
format: int32
reference:
type: string
description: Reference of the transaction. Max length 255 characters.
customer_ip:
type: string
description: RFC791-compliant IP address
currency:
type: string
description: Three letter [ISO currency code](https://pmnts.readme.io/v1.0/docs/iso-currency-codes-1), in UPPERCASE
default: AUD
card_number:
type: string
description: Card number
card_holder:
type: string
description: Name of the card holder
card_expiry:
type: string
description: 'Format: `MM/YYYY`'
card_token:
type: string
cvv:
type: string
description: CVV card number. (3/4 characters)
metadata:
type: object
properties: {}
addendum_data:
type: string
fraud:
properties:
device_id:
type: string
description: The fraud screening service device fingerprint ID. See the Device ID section below for further details
device:
type: object
required:
- uid
properties:
uid:
type: string
description: The device identifier such as IMEI in android or identifier for vendor in iOS. Maximum length is 128 characters.
os_type:
type: string
description: 'The operating system running on the user''s device (relevant for native app only). For example: android, ios, etc'
app_version:
type: string
description: 'The version of the merchant application which is running on the user''s device. Maximum length is 50 characters. For example: ''2.0.1'''
brand:
type: string
description: 'The user''s device brand (relevant for native app only). For example: htc, apple, etc'
model:
type: string
description: 'The model of the user''s device (relevant for native app only) Maximum length is 50 characters. For example: ''iPhone X'', ''Galaxy 3''.'
customer:
type: object
description: Details about the customer
required:
- first_name
- last_name
- email
- address_1
- city
- state
- post_code
- country
properties:
first_name:
type: string
description: The customer's first name
last_name:
type: string
description: The customer's last name
email:
type: string
description: The customer's email address
date_of_birth:
type: string
description: The customer's date of birth, if available
format: date
id:
type: string
description: The customer record ID in the merchant database, if available
address_1:
type: string
description: The customer's primary address line
address_2:
type: string
description: The customer's secondary address line (such as building name)
city:
type: string
description: The customer's city
state:
type: string
description: The customer's state
post_code:
type: string
description: The customer's post code
country:
type: string
description: The ISO 8166 alpha-3 country code for the customer
existing_customer:
type: boolean
description: Indicates if this customer is already in the merchants records or not
created_at:
type: string
description: The date/time that the customer record was created
format: date
home_phone:
type: string
description: The customer's primary phone number. This can be a mobile number, if a home phone number is not provided. Required field for Forter.
shipping_address:
type: object
required:
- first_name
- last_name
- email
- home_phone
- address_1
- city
- state
- post_code
- country
- shipping_method
properties:
first_name:
type: string
description: The shipping address first name
last_name:
type: string
description: The shipping address last name
email:
type: string
description: The shipping address email
home_phone:
type: string
description: The shipping address phone number
address_1:
type: string
description: The shipping address primary address line
address_2:
type: string
description: The shipping address secondary address line (such as building name)
city:
type: string
description: The shipping address city or suburb
state:
type: string
description: The shipping address state
post_code:
type: string
description: The shipping address post code
country:
type: string
description: The ISO 3166 alpha-3 country code for the shipping address
shipping_method:
type: string
description: 'One of the following shipping options: low_cost, same_day, overnight, express, international, pickup, other If none of these options apply choose the closest match.'
recipients:
type: array
description: Recipients are only required if the recipient differs from the shipping address, or if the order is being multi-shipped
items:
properties:
title:
type: string
description: The recipient title/salutation (e.g. Mr, Mrs, Dr)
first_name:
type: string
description: The recipients first name
last_name:
type: string
description: The recipients last name
email:
type: string
description: The recipients email address
address_1:
type: string
description: The recipients primary address line
address_2:
type: string
description: The recipients secondary address line (such as building name)
city:
type: string
description: The recipients city or suburb
state:
type: string
description: The recipients state
post_code:
type: string
description: The recipients post code
country:
type: string
description: The recipients country code - ISO 3166 alpha-3
phone_number:
type: string
description: The recipients phone number
required:
- title
- first_name
- last_name
- email
- address_1
- city
- state
- post_code
- country
type: object
items:
type: array
items:
properties:
product_code:
type: string
description: The product code (base level product code)
sku:
type: string
description: The product SKU (the stock keeping unit code, for example size/color variants)
description:
type: string
description: The description of the product. For longer descriptions (greater then 26 chars) truncate item specifics and add the truncated information to the gift_message field
qty:
type: integer
description: The quantity of items ordered
format: int32
cost:
type: number
description: The base-cost for the product
format: double
line_total:
type: number
description: The line total for the product (cost times quantity)
format: double
tracking_number:
type: string
description: The shipping tracking number for this item
gift_message:
type: string
description: Addendum product description, or gift message
part_number:
type: string
description: The manufacturers part number (if applicable)
shipping_comments:
type: string
description: Any comments for shipping of the item
required:
- product_code
- description
- qty
- cost
- line_total
type: object
custom:
properties:
x:
type: string
description: Custom data for the fraud screening. This is usually agreed upon and configured with the fraud provider. Please discuss using these fields with Support should you require assistance. x may be numerical or a string.
required: []
type: object
website:
type: string
description: The URL for the website where the order is being placed.
required:
- device_id
- device
- customer
- recipients
- items
- website
type: object
responses:
'200':
description: '200'
content:
application/json:
examples:
Fraud Declined:
value: "{\n \"successful\": true,\n \"response\": {\n \"authorization\": \"0\",\n \"id\": \"071-P-RHN5DC15\",\n \"card_number\": \"512345XXXXXX2346\",\n \"card_holder\": \"Jim Smith\",\n \"card_expiry\": \"2023-05-31\",\n \"card_token\": \"pfjeiyx4fk0uko3ev4kd\",\n \"card_type\": \"MasterCard\",\n \"card_category\": \"Credit\",\n \"card_subcategory\": \"Standard\",\n \"amount\": 1000,\n \"decimal_amount\": 10.0,\n \"successful\": false,\n \"message\": \"Declined.\",\n \"reference\": \"Ud5CfaAlwTKJi2kfsAesdAwvIk2fpJjP\",\n \"currency\": \"USD\",\n \"transaction_id\": \"071-P-RHN5DC15\",\n \"settlement_date\": null,\n \"transaction_date\": \"2018-10-09T14:01:06+11:00\",\n \"response_code\": \"01\",\n \"captured\": false,\n \"captured_amount\": null,\n \"rrn\": \"0\",\n \"cvv_match\": \"U\",\n \"metadata\": {},\n \"addendum_data\": {},\n \"fraud_result\": \"Deny\",\n \"fraud_messages\": [\n \"An attribute associated with an Order matched a pre-configured 'Always Deny' rule.\"\n ]\n },\n \"errors\": [],\n \"test\": true\n}"
schema:
type: object
properties:
successful:
type: boolean
example: true
default: true
response:
type: object
properties:
authorization:
type: string
example: '0'
id:
type: string
example: 071-P-RHN5DC15
card_number:
type: string
example: 512345XXXXXX2346
card_holder:
type: string
example: Jim Smith
card_expiry:
type: string
example: '2023-05-31'
card_token:
type: string
example: pfjeiyx4fk0uko3ev4kd
card_type:
type: string
example: MasterCard
card_category:
type: string
example: Credit
card_subcategory:
type: string
example: Standard
amount:
type: integer
example: 1000
default: 0
decimal_amount:
type: integer
example: 10
default: 0
successful:
type: boolean
example: false
default: true
message:
type: string
example: Declined.
reference:
type: string
example: Ud5CfaAlwTKJi2kfsAesdAwvIk2fpJjP
currency:
type: string
example: USD
transaction_id:
type: string
example: 071-P-RHN5DC15
settlement_date: {}
transaction_date:
type: string
example: '2018-10-09T14:01:06+11:00'
response_code:
type: string
example: '01'
captured:
type: boolean
example: false
default: true
captured_amount: {}
rrn:
type: string
example: '0'
cvv_match:
type: string
example: U
metadata:
type: object
properties: {}
addendum_data:
type: object
properties: {}
fraud_result:
type: string
example: Deny
fraud_messages:
type: array
items:
type: string
example: An attribute associated with an Order matched a pre-configured 'Always Deny' rule.
errors:
type: array
test:
type: boolean
example: true
default: true
deprecated: false
x-readme:
code-samples:
- language: curl
code: "curl https://gateway.pmnts-sandbox.io/v1.0/purchases -u TEST:TEST -d' \n { \n \"card_holder\": \"Jim Smith\", \n \"card_number\": \"5123456789012346\", \n \"card_expiry\": \"05/2023\", \n \"cvv\": \"987\", \n \"amount\": 1000, \n \"reference\": \"fd792da68ea1b8a1ba791zzzfc6f73b4\", \n \"customer_ip\": \"111.222.111.123\", \n \"currency\": \"USD\", \n \"fraud\": { \n \"device_id\": \"04003h...truncated...y16eGlPDmAXrXEYZfU=\",\n \"device\": {\n \"uid\": \"625400941054585\",\n \"os_type\": \"android\",\n \"app_version\": \"2.1\",\n \"brand\": \"Samsung\",\n \"model\": \"Galaxy 3\"\n },\n \"customer\": { \n \"address_1\": \"23 Smith Road\", \n \"city\": \"Canberra\", \n \"country\": \"AUS\", \n \"created_at\": \"2014-05-28T21:38:51+11:00\", \n \"date_of_birth\": \"1994-05-28\", \n \"email\": \"deny@email.com\", \n \"existing_customer\": true, \n \"first_name\": \"James\", \n \"home_phone\": \"0421858999\", \n \"id\": \"ABD123\", \n \"last_name\": \"Smith\", \n \"post_code\": \"2600\" \n }, \n \"items\": [ \n { \n \"cost\": 23.3, \n \"description\": \"Widgets\", \n \"line_total\": 23.3, \n \"product_code\": \"9999-A\", \n \"qty\": 1, \n \"sku\": \"9999\" \n } \n ], \n \"recipients\": [\n {\n \"address_1\": \"1 Fairfield Road\",\n \"city\": \"Austin\",\n \"country\": \"USA\",\n \"email\": \"james@smith.com\",\n \"first_name\": \"James\",\n \"last_name\": \"Smith\",\n \"phone_number\": \"555-555-55555\",\n \"post_code\": \"55555-1234\",\n \"state\": \"TX\"\n }\n ],\n \"shipping_address\": {\n \"first_name\": \"James\",\n \"last_name\": \"Smith\",\n \"email\": \"deny@email.com\",\n \"home_phone\": \"0421858999\",\n \"address_1\": \"23 Smith Road\",\n \"city\": \"Canberra\",\n \"country\": \"AUS\",\n \"state\": \"NSW\",\n \"post_code\": \"2600\",\n \"shipping_method\": \"express\"\n }, \n \"custom\": { \n \"3\": \"Facebook\" \n }, \n \"website\": \"http://www.website.com\" \n } \n }'"
- language: ruby
code: "FatZebra::Purchase.create(\n amount: 1000,\n card_holder: 'Jim Smith',\n card_number: '5123456789012346',\n card_expiry: '05/2023',\n cvv: '987',\n reference: 'ORD98976',\n customer_ip: '111.222.111.123'\n)"
samples-languages:
- curl
- ruby
tags:
- Purchases
get:
summary: List purchases
description: ''
operationId: list-purchases
parameters:
- name: offset
in: query
description: Offset to start
schema:
type: integer
format: int32
default: 1
- name: limit
in: query
description: Number of purchases in the response
schema:
type: integer
format: int32
default: 10
- name: from
in: query
description: Lower bound for the time at which the purchase was created
schema:
type: string
format: date
- name: to
in: query
description: Upper bound for the time at which the purchase was created
schema:
type: string
format: date
- name: Content-Type
in: header
description: application/json
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"successful\": true,\n \"response\": [\n {\n \"authorization\": \"512407\",\n \"id\": \"071-P-P7OX5AF6\",\n \"card_number\": \"512345XXXXXX2346\",\n \"card_holder\": \"Matthew Savage\",\n \"card_expiry\": \"2030-02-28\",\n \"card_token\": \"fke86c5u\",\n \"card_type\": \"MasterCard\",\n \"card_category\": \"Credit\",\n \"card_subcategory\": \"Standard\",\n \"amount\": 10000,\n \"decimal_amount\": 100.0,\n \"successful\": true,\n \"message\": \"Approved\",\n \"reference\": \"73a34343849d71bca9ab1a11225a3139-1\",\n \"currency\": \"AUD\",\n \"transaction_id\": \"071-P-P7OX5AF6\",\n \"settlement_date\": \"2017-07-03\",\n \"transaction_date\": \"2017-07-03T12:39:02+10:00\",\n \"response_code\": \"00\",\n \"captured\": true,\n \"captured_amount\": 10000,\n \"rrn\": \"071PP7OX5AF6\",\n \"cvv_match\": \"M\",\n \"metadata\": {},\n \"addendum_data\": {}\n },\n {\n \"authorization\": \"138504\",\n \"id\": \"071-P-4AXUY9Q4\",\n \"card_number\": \"512345XXXXXX2346\",\n \"card_holder\": \"Matthew Savage\",\n \"card_expiry\": \"2030-02-28\",\n \"card_token\": \"fke86c5u\",\n \"card_type\": \"MasterCard\",\n \"card_category\": \"Credit\",\n \"card_subcategory\": \"Standard\",\n \"amount\": 10000,\n \"decimal_amount\": 100.0,\n \"successful\": true,\n \"message\": \"Approved\",\n \"reference\": \"bfe2f0f43e2f6811161ae7a009b3c840-0\",\n \"currency\": \"AUD\",\n \"transaction_id\": \"071-P-4AXUY9Q4\",\n \"settlement_date\": \"2017-07-03\",\n \"transaction_date\": \"2017-07-03T12:39:01+10:00\",\n \"response_code\": \"00\",\n \"captured\": true,\n \"captured_amount\": 10000,\n \"rrn\": \"071P4AXUY9Q4\",\n \"cvv_match\": \"M\",\n \"metadata\": {},\n \"addendum_data\": {}\n }\n ],\n \"errors\": [],\n \"records\": 2,\n \"total_records\": 2,\n \"page\": 1,\n \"total_pages\": 1\n}\n"
schema:
type: object
properties:
successful:
type: boolean
example: true
default: true
response:
type: array
items:
type: object
properties:
authorization:
type: string
example: '512407'
id:
type: string
example: 071-P-P7OX5AF6
card_number:
type: string
example: 512345XXXXXX2346
card_holder:
type: string
example: Matthew Savage
card_expiry:
type: string
example: '2030-02-28'
card_token:
type: string
example: fke86c5u
card_type:
type: string
example: MasterCard
card_category:
type: string
example: Credit
card_subcategory:
type: string
example: Standard
amount:
type: integer
example: 10000
default: 0
decimal_amount:
type: integer
example: 100
default: 0
successful:
type: boolean
example: true
default: true
message:
type: string
example: Approved
reference:
type: string
example: 73a34343849d71bca9ab1a11225a3139-1
currency:
type: string
example: AUD
transaction_id:
type: string
example: 071-P-P7OX5AF6
settlement_date:
type: string
example: '2017-07-03'
transaction_date:
type: string
example: '2017-07-03T12:39:02+10:00'
response_code:
type: string
example: '00'
captured:
type: boolean
example: true
default: true
captured_amount:
type: integer
example: 10000
default: 0
rrn:
type: string
example: 071PP7OX5AF6
cvv_match:
type: string
example: M
metadata:
type: object
properties: {}
addendum_data:
type: object
properties: {}
errors:
type: array
records:
type: integer
example: 2
default: 0
total_records:
type: integer
example: 2
default: 0
page:
type: integer
example: 1
default: 0
total_pages:
type: integer
example: 1
default: 0
deprecated: false
x-readme:
code-samples:
- language: curl
code: curl https://gateway.pmnts-sandbox.io/v1.0/purchases -u TEST:TEST
- language: ruby
code: FatZebra::DirectCredit.search
samples-languages:
- curl
- ruby
tags:
- Purchases
/purchases/:
post:
summary: Create a purchase using a wallet
description: ''
operationId: create-a-purchase-with-wallet
parameters:
- name: Content-Type
in: header
description: application/json
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
required:
- amount
- reference
- customer_ip
- currency
- card_holder
properties:
amount:
type: integer
description: A positive integer representing how much to charge, in the smallest currency unit (eg., 100 to charge $1.00, or 100 to Charge ¥100, a zero decimal currency)
format: int32
reference:
type: string
description: Reference of the transaction. Max length 255 characters.
customer_ip:
type: string
description: RFC791-compliant IP address
currency:
type: string
description: Three letter [ISO currency code](https://pmnts.readme.io/v1.0/docs/iso-currency-codes-1), in UPPERCASE
default: AUD
card_holder:
type: string
description: Name of the card holder
cvv:
type: string
description: CVV card number. (3/4 characters)
test:
type: boolean
description: Indicates if this is a test transaction
default: false
wallet:
type: object
description: Wallet credentials. Described below
required:
- type
properties:
type:
type: string
description: Name of the wallet ('ApplePay', 'GooglePay')
encPaymentData:
type: string
description: 'required for type: VISA'
encKey:
type: string
description: 'required for type: VISA'
callid:
type: string
description: 'required for type: VISA'
token:
type: string
description: 'required for type: APPLE, GOOGLE'
user_id:
type: string
description: 'required for type: MASTER
# --- truncated at 32 KB (163 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fat-zebra/refs/heads/main/openapi/fat-zebra-purchases-api-openapi.yml