{"info":{"_postman_id":"61614681-baf1-4874-93b7-9ba33e4e7226","name":"Paybomb API Documentation","description":"

Overview

Paybomb is a payment gateway optimization and intelligence service that merchants can use to provide a remote and frictionless payment experience.

This documentation will help you get started with integrating Paybomb but if you have any questions, please do not hesitate to reach out to us via email at info@paybomb.tech

Please be advised that our support team is only available during standard business hours.

Environments

These are the BaseUrls for the APIs on different environments:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Environment	Base URL
Production	https://app.paybomb.tech/api/v1
Sandbox	https://app.paybomb.tech/api/v1 `Note: set the Sandbox flag true (checked) in your merchant account. As shown in the image below`

Authentication

To access the API, you must acquire your unique API key from the merchant dashboard -> API Keys section in your account. Make sure to use this key as a bearer token in the Authorization header for every request you send.

AUTHORIZATION: Bearer Token

Token: {{APIKey}} .

Access your sandbox API key credentials by navigating to your merchant login and checking the 'is sandbox' option, located in the top right corner under merchant profile.

\n\n

To get to the live API key, uncheck the 'Is Sandbox' option in the top right corner of your merchant dashboard. After unchecking, the page will refresh, and you can generate an API key for live transactions in this environment.\"

\n\n

Reiterating, the API keys in Sandbox mode are for testing (when 'is sandbox' is CHECKED in the top right corner under merchant profile). The live API key credentials are for processing actual card transactions in Live mode (when 'is sandbox' is UNCHECKED in the same location)

Request Headers

Use these headers on every API call unless noted.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Header	Value	Required	Notes
`Content-Type`	`application/json`	Yes	All endpoints. Send JSON payloads.
`Authorization`	`Bearer {MERCHANT_API_KEY}`	Yes	All endpoints. Replace with your merchant API key.
`BrandId`	`{YOUR_BRAND_ID}`	Conditional	Session and CustomerAPIs. optional in customer APIs but Mandatory in Session APIs

","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Overview","slug":"overview"},{"content":"Environments","slug":"environments"},{"content":"Authentication","slug":"authentication"},{"content":"Request Headers","slug":"request-headers"}],"owner":"54431596","collectionId":"61614681-baf1-4874-93b7-9ba33e4e7226","publishedId":"2sBXqKq15h","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2026-05-04T13:25:58.000Z"},"item":[{"name":"⚙️ Integration Steps","item":[],"id":"333f2379-db80-48dc-9bb4-898f7469d4ba","description":"

To start integrating you should already have your Merchant access to our admin portal and sandbox credentials which you will need to complete the integration.

1. Setup & check merchant details

The first step in getting your integration ready is to check whether all the details about you as a merchant are correct on our Merchant portal. If you detect anomalies, then please contact your Account Manager.

Start with sandbox mode (see top right-hand corner on your merchant portal to toggle between modes) and generate API Key, Brand ID and Public Key and also set up the callback URLs for subscribing to webhooks.

API Key - necessary to send transactions via API
\n
Brand ID - needed to send transaction. Use different brand IDs for different shops or brands.
\n
Public Key - needed to signature verification received in headers of the webhook
\n
Webhook - recommended to get notifications from our server to your server to inform you of transaction status changes and notifications about transactions. You can check all the details of how our webhooks work on the Webhooks page.
\n

2. Test the integration in Sandbox Mode

After finishing your integration, make sure your code is working as intended and test the purchase flow in the staging environment.

Testing Credentials (only on Sandbox mode)

You have the opportunity to test the APIs by performing test purchases using the below test cards. We have introduced new test cards from 18th December 2025 onwards, which will have more exhaustive error messages helping you test different types of card transactions.

The cards mentioned above will stop working and the below mentioned cards will be used:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

card_type	Card Numbers	auth_type	Behaviour
Master	5141922635866282	3D Secure	Authentication Successful
Master	5169811636324572	3D Secure	Authentication Failed
Master	5143312606271514	2D Secure	Insufficient funds
Master	5199805409482512	2D Secure	Pending execution
Master	5146669487735546	2D Secure	Incorrect card expiry
Master	5151735930865446	3D Secure	Incorrect cvv
Master	5185151885032695	3D Secure	Processor timeout
Master	5149446104369687	2D Secure	Refund failed
Master	5127160683722580	3D Secure	Transaction expired
Master	5159971600530380	3D Secure	Risk check failed
Master	5198134892284199	2D Secure	Issuer decline
Master	5116213113429327	2D Secure	Authentication successful
Master	5112857124909935	2D Secure	Authentication failed
Master	5156216152193051	3D Secure	Insufficient funds
Master	5170361568993009	3D Secure	Pending execution
Master	5559161923541480	3D Secure	Incorrect card expiry
Master	5110339832985475	2D Secure	Incorrect cvv
Master	5136528486494418	2D Secure	Processor timeout
Master	5162164630471008	3D Secure	Refund failed
Master	5140378358642890	2D Secure	Transaction expired
Master	5192488343990234	2D Secure	Risk check failed
Master	5115438560834809	3D Secure	Issuer decline
VISA	4079722589318630	2D Secure	Authentication successful
VISA	4878397953290146	3D Secure	Authentication successful
VISA	4125485445527190	2D Secure	Authentication failed
VISA	4984823599573265	3D Secure	Insufficient funds
VISA	4710793097358785	2D Secure	Pending execution
VISA	4500682811540204	3D Secure	Incorrect card expiry
VISA	4935648707390280	2D Secure	Incorrect cvv
VISA	4241214813524459	3D Secure	Refund failed
VISA	4342346318195134	3D Secure	Risk check failed
VISA	4618889598319798	3D Secure	Issuer decline
VISA	4195258724913240	3D Secure	Authentication failed
VISA	4662922293431520	2D Secure	Insufficient funds
VISA	4994455060632359	3D Secure	Pending execution
VISA	4460652052832634	2D Secure	Incorrect card expiry
VISA	4383025225665997	3D Secure	Incorrect cvv
VISA	4568730114361775	2D Secure	Processor timeout
VISA	4163340122068617	3D Secure	Processor timeout
VISA	4405935956954713	2D Secure	Refund failed
VISA	4945208335596614	2D Secure	Transaction expired
VISA	4566329901944380	3D Secure	Transaction expired
VISA	4588381711517694	2D Secure	Risk check failed
VISA	4401279985739470	2D Secure	Issuer decline

Note:
You can enter any expiry month and year which is larger or equal to the current month/year.
You can enter any cvv.
OTP will only be 123456 for 3ds cases.

Currently, only card payment testing is supported in the sandbox environment. Testing Alternative Payment Methods (APMs) is not available in the sandbox at this time.

3. Create and test credentials on the Live Mode

After finishing your integration in sandbox mode, set up your production environment by turning off the sandbox mode from merchant dashboard and following the same steps mentioned in step one. Test the integration using small amounts to ensure everything is working.

4. Go live!

Inform your Account Manager when the setup is done to get started with processing live traffic.

Overview

When a transaction status changes to a terminal state (e.g., paid, refunded, expired), our payment gateway sends a server-to-server POST callback to the merchant's configured Webhook URL.

The callback includes full transaction details so the merchant can update order status in real time.

Webhook Events for Payins

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Event type	Status	When is the event triggered	Is this a terminal event?
purchase created	`created`	Triggered when a new purchase request is initialized and recorded in the system.	❌ No
payment in process	`payment_in_process`	Triggered when the payment is initiated and awaiting confirmation from the PSP/bank.	❌ No
purchase overdue	`overdue`	Triggered when a purchase remains in the CREATED state and the configured Transaction Overdue Hours (from Admin Settings) have elapsed, the system automatically updates the purchase status to OVERDUE	❌ No (may lead to failed/expired/paid later)
purchase paid	`paid`	Triggered when the payment is successfully completed and confirmed.	✅ Yes
purchase failed	`error`	Triggered when the payment attempt fails due to technical error, insufficient funds, or rejection by PSP/bank.	✅ Yes
purchase cancelled	`cancelled`	Triggered when the customer or system cancels the purchase before completion.	✅ Yes
purchase expired	`expired`	Triggered when the purchase is not paid within the allowed expiry time.	✅ Yes
refund in process	`refund_in_process`	Triggered when a refund has been initiated but is not yet completed/settled.	❌ No
payment refund	`refunded` / `fraud_refunded`	Triggered when the completed payment is refunded, refunded due to fraud, or reversed via chargeback.	✅ Yes
Chargeback	`chargeback`	Triggered when a chargeback is applied	✅ Yes

Webhook Payload Specification

Fields Description

Key	Description
message.purchaseId	Unique identifier of the purchase generated by Paybomb.
message.client	Customer’s ID in merchant’s system (if available), otherwise \"NA\".
message.client.email	Customer’s email address.
message.client.phone	Customer’s phone number (with country code).
message.client.full_name	Full name of the customer.
message.client.date_of_birth	Customer’s date of birth in YYYY-MM-DD format.
message.client.street_address	Customer’s full street address.
message.client.country	ISO 2-letter country code of the customer.
message.client.city	City name (and state, if applicable).
message.client.zip_code	Postal / ZIP code.
message.client.stateCode	ISO 2-letter state code.
message.updated_on	UNIX timestamp of the last update to the transaction.
message.type	Type of transaction (e.g., \"purchase\").
message.paymentMethod	Comma-separated list of payment methods used (e.g., \"MASTER,VISA,JCB\").
message.amountUnit	Unit of amount — \"MAJOR\" for full currency unit, \"MINOR\" for subunits.
message.errorMsg	Message describing the transaction result — success message or error details.
message.created_on	UNIX timestamp when the purchase was created.
message.merchantRef	Unique transaction reference from the merchant.
message.merchantName	Registered merchant name in Paybomb.
message.purchase.currency	Currency code (ISO 4217).
message.purchase.products	Array of product details (name, quantity, price, discount, tax).
message.purchase.total	Total amount for all products (in amount unit).
message.purchase.language	Language code for the transaction (ISO 639-1).
message.payment.payment_type	Type of payment (e.g., \"PURCHASE\").
message.payment.amount	Payment amount.
message.payment.currency	Payment currency.
message.payment.paid_on	UNIX timestamp when the payment was completed.
message.status	Current transaction status.
message.status_history	Array of all past statuses with timestamps.
message.reference	Paybomb’s unique transaction reference.
status (root-level)	Duplicate of current status for quick access.

Possible Status Values

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

status	description
error	purchase failed due to an error.
cancelled	purchase was cancelled by the user or system.
created	purchase record created but not paid yet.
expired	payment link or session expired.
overdue	payment overdue.
paid	payment completed successfully.
refunded	payment refunded.
fraud_refunded	refunded due to fraud detection.
chargeback	reversed due to chargeback.
payment_in_process	payment is in progress.
refund_in_process	refund process started but not completed.

🔐 Key Pair Generation

Paybomb uses RSA key pairs to digitally sign webhooks, ensuring all notifications are both secure and authentic.

1. Generate Your Keys

\n\n

Click “Generate Key Pair” in the dashboard.
\n
A unique RSA private key and public key are created for your merchant ID.
\n

2. Key Storage

\n\n

Private Key → Stored securely by Paybomb (never exposed).
\n
Public Key → Displayed to you once on the screen. Copy and save it for verifying signatures.
\n

3. Webhook Signing

Every webhook payload is signed using Paybomb’s private key.
\n
The signature is included in webhook headers:
\n
- paybomb-sign or paybomb_sign
\n

4. Verification

Use your public key to verify the paybomb-sign header against the webhook body.
\n
This ensures the webhook came from Paybomb and was not tampered with.
\n

🔏 Signature: paybomb-sign (or paybomb_sign)

The paybomb-sign header is a Base64-encoded digital signature generated using your merchant-specific RSA private key.

🔨 How the Signature is Generated

Message Construction

Concatenate the following fields in order:

{purchaseId}|{message.status}|{brandId}\n\n

Example

1234567890|PAID|BRAND_001\n\n

2. Signing Algorithm

Algorithm: SHA256withRSA
\n
Output: Base64-encoded signature (sent in the paybomb-sign header).
\n

✅ How to Verify the Signature

Rebuild the Message

From the webhook JSON body, extract:

purchaseId
\n
status (convert to uppercase)
\n
brandId
\n

Reconstruct the string in the same format:
{purchaseId}|{message.status}|{brandId}

2. Verification Steps

Use your stored public key.
\n
Decode the paybomb-sign header from Base64.
\n
Verify using SHA256withRSA.
\n
If verification succeeds, the webhook is authentic and untampered.
\n

💻 Java Verification Example

public static boolean verifySignature(String message, String signatureBase64, PublicKey publicKey) throws Exception {\n    Signature signature = Signature.getInstance(\"SHA256withRSA\");\n    signature.initVerify(publicKey);\n    signature.update(message.getBytes());\n    byte[] signatureBytes = Base64.getDecoder().decode(signatureBase64);\n    return signature.verify(signatureBytes);\n}\n\n

message → The reconstructed string (purchaseId|STATUS|brandId)
\n
signatureBase64 → Value from paybomb-sign header
\n
publicKey → Your saved Paybomb public key
\n

Sample Webhook

{\n  \"message\": {\n    \"purchaseId\": \"6808127876673d75156df3e6\",\n    \"client\": {\n      \"customerId\": \"NA\",\n      \"email\": \"daler101@hotmail.com\",\n      \"phone\": \"+17808752869\",\n      \"full_name\": \"Dale Richardson\",\n      \"date_of_birth\": \"1800-01-01\",\n      \"street_address\": \"48 AVE , ALBERTA BEACH\",\n      \"country\": \"CA\",\n      \"city\": \"ALBERTA\",\n      \"zip_code\": \"T0E 0A0\",\n      \"shipping_street_address\": \" \",\n      \"shipping_country\": \"\",\n      \"shipping_city\": \"\",\n      \"shipping_zip_code\": \"\",\n      \"cc\": [],\n      \"bcc\": [],\n      \"stateCode\": \"AB\"\n    },\n    \"updated_on\": 1745359929,\n    \"type\": \"purchase\",\n    \"isFraud\": \"NO\",\n    \"paymentMethod\": \"INTERAC,MASTER,VISA,JCB\",\n    \"amountUnit\": \"MAJOR\",\n    \"errorMsg\": \"Transaction succeeded-APPROVED\",\n    \"detailedMsg\": \"Transaction succeeded-APPROVED\",\n    \"redirectType\": \"POST\",\n    \"force_recurring\": false,\n    \"created_on\": 1745359481,\n    \"merchantRef\": \"7235\",\n    \"merchantName\": \"firstinvestacademy\",\n    \"pspReference\": \"pKlSYNsPOdOL2FCmSAjXEOHzDDpSP5\",\n    \"bankmid\": \"waverlite\",\n    \"bankname\": \"waverlite\",\n    \"purchase\": {\n      \"currency\": \"CAD\",\n      \"products\": [\n        {\n          \"name\": \"Payment\",\n          \"quantity\": 1,\n          \"price\": 294,\n          \"discount\": 0,\n          \"tax_percent\": \"0.00\"\n        }\n      ],\n      \"total\": 294,\n      \"language\": \"en\",\n      \"notes\": \"Micro+ Plan\",\n      \"debt\": 0,\n      \"total_formatted\": 1,\n      \"expireInMin\": \"43800\",\n      \"taxAmount\": 0,\n      \"taxPercent\": 0,\n      \"request_client_details\": [],\n      \"email_message\": \"\"\n    },\n    \"payment\": {\n      \"is_outgoing\": false,\n      \"payment_type\": \"PURCHASE\",\n      \"amount\": 294,\n      \"currency\": \"CAD\",\n      \"net_amount\": 294,\n      \"fee_amount\": 0,\n      \"pending_amount\": 0,\n      \"pending_unfreeze_on\": null,\n      \"description\": \"\",\n      \"paid_on\": 1745359487,\n      \"remote_paid_on\": 1745359487\n    },\n    \"issuer_details\": {\n      \"website\": \"\",\n      \"legal_street_address\": \"\",\n      \"legal_country\": \"\",\n      \"legal_city\": \"\",\n      \"legal_zip_code\": \"\",\n      \"bank_accounts\": [\n        {}\n      ],\n      \"legal_name\": \"FISCOM\",\n      \"brand_name\": \"FISCOM\",\n      \"registration_number\": \"\",\n      \"tax_number\": \"\"\n    },\n    \"transaction_data\": {\n      \"payment_method\": \"\",\n      \"flow\": \"payform\",\n      \"extra\": {\n        \"amount\": 294,\n        \"masked_pan\": \"INTERAC\"\n      },\n      \"country\": \"\",\n      \"attempts\": [\n        {\n          \"client_ip\": \"185.199.101.249\",\n          \"type\": \"execute\",\n          \"payment_method\": \"INTERAC\",\n          \"flow\": \"payform\",\n          \"successful\": true,\n          \"country\": \"INTERAC\",\n          \"processing_time\": 1745359487,\n          \"extra\": {\n            \"amount\": 294,\n            \"masked_pan\": \"INTERAC\"\n          }\n        }\n      ]\n    },\n    \"status\": \"PAID\",\n    \"status_history\": [\n      {\n        \"status\": \"created\",\n        \"timestamp\": 1745359481\n      },\n      {\n        \"status\": \"pending_execute\",\n        \"timestamp\": 1745359487\n      },\n      {\n        \"status\": \"payment_in_process\",\n        \"timestamp\": 1745359491\n      },\n      {\n        \"status\": \"viewed\",\n        \"timestamp\": 1745359500\n      },\n      {\n        \"status\": \"paid 294.0\",\n        \"timestamp\": 1745359929\n      }\n    ],\n    \"viewedOn\": 1745359932,\n    \"is_test\": false,\n    \"brand_id\": \"88f25364-8d96-4c2f-8dae-d4aa2756e4e3\",\n    \"send_receipt\": false,\n    \"is_recurring_token\": false,\n    \"skip_capture\": false,\n    \"reference_generated\": \"PS4754\",\n    \"reference\": \"7235\",\n    \"issued\": \"2025-04-22\",\n    \"due\": 1745359481,\n    \"refund_upto\": 0,\n    \"cc_descriptor\": \"Africhange Technologies\",\n    \"fraudScore\": \"NA\",\n    \"trustScore\": \"NA\",\n    \"fx_Currency\": \"CAD\",\n    \"fx_Amount\": \"294.00\",\n    \"transFees\": \"0.44\",\n    \"refundFee\": \"NA\",\n    \"chargeBackFee\": \"NA\",\n    \"rollingReserve\": \"0.00\",\n    \"cascade_Num\": \"NA\",\n    \"debitOrcredit\": \"NA\",\n    \"conversionRiskFactorApplied\": \"0\",\n    \"payInDetails\": {\n      \"name\": \"INTERAC E-TRANSFER\",\n      \"emailAddress\": \"transfer@ieft.ca\",\n      \"secretQA\": \"q4754199\",\n      \"secretAnswer\": \"a4754199\"\n    },\n    \"paidOn\": 1745359929,\n    \"receivedAmt\": 294,\n    \"refund_availability\": \"NONE\",\n    \"refundable_amount\": 0,\n    \"success_redirect\": \"https://firstinvestschool.com/?wc-api=wc_gateway_payments&id=7235&action=paid\",\n    \"failure_redirect\": \"https://firstinvestschool.com/?wc-api=wc_gateway_payments&id=7235&action=cancel\",\n    \"cancel_redirect\": \"https://firstinvestschool.com/?wc-api=wc_gateway_payments&id=7235&action=cancel\",\n    \"success_callback\": \"https://firstinvestschool.com/?wc-api=wc_gateway_payments&id=7235&action=paid\",\n    \"failure_callback\": \"\",\n    \"creator_agent\": \"Paybomb Payments for WooCommerce: v1.2.3\",\n    \"platform\": \"API\",\n    \"created_from_ip\": \"54.229.186.248, 172.70.58.20, 15.158.56.19\",\n    \"checkout_url\": \"https://api.choicepay.ca/payments/6808127876673d75156df3e6/\",\n    \"direct_post_url\": \"https://api.choicepay.ca/api/v1/p/6808127876673d75156df3e6/\",\n    \"mdr\": \"13.52\",\n    \"payoutProcess\": false\n  },\n  \"status\": \"paid\"\n}\n\n

\n","_postman_id":"4f2ccc76-3168-4846-a558-93ada3d4a5bd"},{"name":"Payout","item":[],"id":"36e6adf0-005d-4f25-ad8a-c2543f6c4874","description":"

Overview

When a transaction status changes to a terminal state (e.g., paid, pending_review (in development)), our payment gateway sends a server-to-server POST callback to the merchant's configured Webhook URL.

The callback includes full transaction details so the merchant can update order status in real time.

Webhook Events for Payouts

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Event type (Condition applied in code)	Status	When is the event triggered	Is this a terminal event
Payout – Created	created	When the payout request is created	No
Payout – in Process	payout_in_process	When the Payout request is triggered to the bank, and the status is in pending	No
Payout – Pending Review	pending_review	When the payout request needs manual review from the merchant	No
payout – failure	error	Triggered when the payout request fails (system/PSP error, rejection, etc.).	✅ Yes
payout – success	paid	Triggered when the payout is processed successfully and funds are released.	✅ Yes

Webhook Payload Specification

Fields Description

Key	Description
payload.payoutId	Unique identifier of the payout generated by Paybomb.
payload.client.customerId	Customer’s ID in the merchant’s system (if available), otherwise \"NA\".
payload.client.email	Customer’s email address.
payload.client.phone	Customer’s phone number (with country code).
payload.client.full_name	Full name of the customer.
payload.client.country	ISO 2-letter country code of the customer.
payload.updated_on	UNIX timestamp of the last update to the payout transaction.
payload.payoutMethod	Payout method used (e.g., \"PAYOUT-INTERAC\").
payload.amountUnit	Unit of amount — \"MAJOR\" for full currency unit, \"MINOR\" for subunits.
payload.amount	Total payout amount.
payload.errorMsg	Message describing the payout result — success message or error details.
payload.purpose	Purpose/description of the payout.
payload.created_on	UNIX timestamp when the payout was created.
payload.merchantRef	Unique transaction reference from the merchant.
payload.merchantName	Registered merchant name in Paybomb.
payload.currency	Currency code of the payout (ISO 4217).
payload.fx_Currency	FX (foreign exchange) currency used (if applicable).
payload.fx_Amount	FX-adjusted payout amount.
payload.transFees	Transaction fee amount.
payload.paymentOn	UNIX timestamp when the payout was completed/paid.
payload.payOutDetails.name	Payout instrument name (e.g., \"INTERAC E-TRANSFER\").
payload.payOutDetails.emailAddress	Payout recipient email address.
payload.payOutDetails.secretQA	Security question used for payout (if applicable).
payload.payOutDetails.secretAnswer	Security answer used for payout (if applicable).
payload.taxAmount	Tax amount applied to the payout.
payload.taxPercent	Tax percentage applied to the payout.
payload.redirectType	Redirect method after payout completion (e.g., \"POST\").
payload.pendingReview	Indicates if the payout is under review (\"Yes\"/\"No\").
payload.surcharge	Surcharge amount applied (if any).
payload.success_callback	Callback URL invoked on payout success.
payload.failure_callback	Callback URL invoked on payout failure.

Possible Status Values

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

status	description
error	Payout failed due to an error.
created	Payout record created but not paid yet.
paid	payment completed successfully.
payout_in_process	Payout is in progress.
pending_review	Payout needs to be reviewed

🔐 Key Pair Generation

Paybomb uses RSA key pairs to digitally sign webhooks, ensuring all notifications are both secure and authentic.

1. Generate Your Keys

\n\n

Click “Generate Key Pair” in the dashboard.
\n
A unique RSA private key and public key are created for your merchant ID
\n

2. Key Storage

\n\n

Private Key → Stored securely by Paybomb (never exposed).
\n
Public Key → Displayed to you once on the screen. Copy and save it for verifying signatures.
\n

3. Webhook Signing

Every webhook payload is signed using Paybomb’s private key.
\n
The signature is included in webhook headers:
\n
- paybomb-sign or paybomb_sign
\n

4. Verification

Use your public key to verify the paybomb-sign header against the webhook body.
\n
This ensures the webhook came from Paybomb and was not tampered with.
\n

🔏 Signature: paybomb-sign (or paybomb_sign)

The paybomb-sign header is a Base64-encoded digital signature generated using your merchant-specific RSA private key.

🔨 How the Signature is Generated

Message Construction

Concatenate the following fields in order:

{payoutId}|{payload.status}\n\n

Example:

1234567890|paid\n\n

2. Signing Algorithm

Algorithm: SHA256withRSA
\n
Output: Base64-encoded signature (sent in the paybomb-sign header).
\n

✅ How to Verify the Signature

Rebuild the Message

From the webhook JSON body, extract:

payoutId
\n
payload.status (convert to lowercase)
\n

Reconstruct the string in the same format:
{payoutId}|{payload.status}

2. Verification Steps

Use your stored public key.
\n
Decode the paybomb-sign header from Base64.
\n
Verify using SHA256withRSA.
\n
If verification succeeds, the webhook is authentic and untampered.
\n

public static boolean verifySignature(String message, String signatureBase64, PublicKey publicKey) throws Exception {\n    Signature signature = Signature.getInstance(\"SHA256withRSA\");\n    signature.initVerify(publicKey);\n    signature.update(message.getBytes());\n    byte[] signatureBytes = Base64.getDecoder().decode(signatureBase64);\n    return signature.verify(signatureBytes);\n}\n\n

message → The reconstructed string (payoutId|status)
\n
signatureBase64 → Value from paybomb-sign header
\n
publicKey → Your saved Paybomb public key
\n

Sample Webhook:

{\n  \"payload\": {\n    \"payoutId\": \"68b02af16c4f71530ae1d73b\",\n    \"client\": {\n      \"customerId\": \"NA\",\n      \"email\": \"ashishm.21190@gmail.com\",\n      \"phone\": \"+14377717874\",\n      \"full_name\": \"Ashish Mistry\",\n      \"country\": \"CA\"\n    },\n    \"updated_on\": 1756375793,\n    \"payoutMethod\": \"PAYOUT-INTERAC-ETRANSFER\",\n    \"amountUnit\": \"MAJOR\",\n    \"amount\": 6,\n    \"errorMsg\": \"\",\n    \"purpose\": \"test payout\",\n    \"created_on\": 1756375793,\n    \"merchantRef\": \"68b02af16c4f71530ae1d73b\",\n    \"merchantName\": \"arunsinghal\",\n    \"status\": \"PAID\",\n    \"status_history\": [\n      {\n        \"status\": \"created\",\n        \"timestamp\": 1756375793\n      },\n      {\n        \"status\": \"paid\",\n        \"timestamp\": 1756375810\n      }\n    ],\n    \"currency\": \"CAD\",\n    \"fx_Currency\": \"CAD\",\n    \"fx_Amount\": \"6.00\",\n    \"transFees\": \"0.3\",\n    \"paymentOn\": 1756375810,\n    \"payOutDetails\": {\n      \"name\": \"INTERAC E-TRANSFER\",\n      \"emailAddress\": \"ashishm.21190@gmail.com\",\n      \"secretQA\": \"q680216471530173202\",\n      \"secretAnswer\": \"a680216471530173202\"\n    },\n    \"taxAmount\": 0,\n    \"taxPercent\": 0,\n    \"redirectType\": \"POST\",\n    \"pendingReview\": \"No\",\n    \"surcharge\": 0,\n    \"success_callback\": \"https://webhook.site/d7660184-d724-480c-bad0-cf0480f5518e\",\n    \"failure_callback\": \"https://webhook.site/d7660184-d724-480c-bad0-cf0480f5518e\",\n    \"mdr\": \"0.00\"\n  },\n  \"status\": \"paid\"\n}\n\n

\n","_postman_id":"36e6adf0-005d-4f25-ad8a-c2543f6c4874"}],"id":"866d6797-1421-4a25-9350-26b855186454","description":"

To receive information about various transaction status and events, you will need to set up an endpoint which accepts payloads sent by Paybomb. Your endpoint will receive POST requests with content-type: application/json.

Configuring the webhook endpoint

The webhook endpoint can be set up on Partner Dashboard -> Webhooks -> New Webhook.

\n\n

Make sure you save the endpoint by clicking \"Create\".

Paybomb will post all payloads to the specified URLs. Please note that if merchant face any issues with accepting the webhook, it will not be resent. Alternatively the merchant can call Paybomb get status API to verify the status of a purchase.

Steps to Configure a Webhook

\n\n

1.Add a New Webhook:

Click on the “New Webhook” button.

2. Provide Details:

Name: Give the webhook a descriptive name.
\n
Payment Method Selection:
\n

a. Choose a specific payment method or select “All” for universal callbacks.

Enter URL:

a. Provide the callback URL where the event notifications will be sent.

3. Select Event Triggers:

a. Choose from a list of available events (Note: Depending on the payment method, not all events may be available.)

4. Save configuration:

a. Click “Save” to store the webhook settings.**

Notes:

You can setup one URL for all the events or individual URLs for each of the events. Paybomb would call the webhooks based on whatever the setup is. If only one URL, the developer will need to extract the message from the payload information.
\n
In case of a success_callback (webhook) or failure_callback (webhook) is given the /purchases API or /createSession API, then priority will be given to API callback webhooks, and not the webhooks set in the merchant dashboard. In other words, the webhooks given in the API will override the webhooks set in the merchant dashboard. The webhook posted would be a JSON object (either purchase or payout object as the case might be) containing the status. This object is the same as the one you will get in the /getStatus API call https://app.paybomb.tech/api/v1/purchases/{purchaseId}/
\n

Available Event for subscription

When a transaction status changes to a terminal state (e.g., paid, refunded, expired), our payment gateway sends a server-to-server POST callback to the merchant's configured Webhook URL.

The callback includes full transaction details so the merchant can update order status in real time.

HTTP Method & Headers

Method: POST

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Header	Description
Content-Type	application/json; charset=utf-8 — Indicates the payload format is JSON in UTF-8 encoding.
User-Agent	Always set to \"Paybomb\" — Identifies the request origin as Paybomb.
paybomb_sign	Present only if a signature value (paybomb_sign) is generated(see the logic below). This is used for validating the authenticity of the callback.
paybomb-sign	Same signature value as paybomb_sign but provided in an alternate header name for better compatibility.

Webhook structure

We add a signature as “paybomb_sign” or \"paybomb-sign\" in the webhook header for verifying the payload, If you have already created a public key from your merchant dashboard.

To verify this signature, decrypt the signature with your public key. Compare this with the values which you received in your payload.

Use the following method (in Java) for signature verification.

 private static boolean verify(String message,String signature, PublicKey publicKey) throws Exception \n{\n    Signature verifier = Signature.getInstance(\"SHA256withRSA\");\n    verifier.initVerify(publicKey);\n    verifier.update(message.getBytes());\n    return verifier.verify(Base64.getDecoder().decode(signature.getBytes()));\n}\n\n

Where the message is the combination of values which you received in the payload:
\n
1. For Payins: the message is a combination of purchaseId+\"|\"+status(uppercase)+\"|\"+brandId
  \n
2. Payouts: this message is a combination of p**ayoutId+\"|\"+status(lowercase)**
  \n
\n
The signature is the value of the “paybomb_sign” or \"paybomb-sign\" you received in webhook.
\n
You can obtain the Public Key from your merchant dashboard.
\n

\n","_postman_id":"866d6797-1421-4a25-9350-26b855186454"},{"name":"🖥️ Status Code","item":[{"name":"Transaction Status and Their Meaning","item":[],"id":"f8790b34-2cbb-4557-b664-e9be5fa45eaf","description":"

The lifecycle of a transaction is reflected through the status of the transaction.

This section details various statuses of a transaction and what it means and when does it appears.

The status of a transaction can be read from the \"status\" field of the responses or webhook payload.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Description	When it Appears	Is it Final?
CREATED	Purchase is created in the system.	When Purchase API is called, the transaction is created as \"CREATED\".	N
CANCELLED	Purchase is cancelled in the system. Only transactions in \"CREATED\" status can be cancelled.	When Cancel API is called.	Y
PENDING EXECUTE	Purchase hasn't been completed yet. Only transactions in \"CREATED\" status can become \"PENDING EXECUTE\" after S2S API call.	The callback URL provided in the S2S call response hasn't been called by merchant yet.	N
OVERDUE	Purchase hasn't been completed yet. Only transactions in \"CREATED\" status can become \"OVERDUE\" if S2S API hasn't been called in 2 hours.	S2S API hasn't been called within 2 hours since transaction creation.	N
EXPIRED	Purchase hasn't been completed. Only transactions in \"PAYMENT IN PROCESS\" and \"PENDING EXECUTE\" status can become \"EXPIRED\". After payment in process, no data is provided.	The callback URL provided in the S2S call response hasn't been called by the merchant after the specific time period.	Y
PAID	Purchase has been completed successfully. Only transactions in \"PAYMENT IN PROCESS\" status can become \"PAID\".	The callback URL provided in the S2S call response has been called by the merchant.	Y
PAYMENT IN PROCESS	Purchase hasn't been completed. Only transactions in \"PENDING EXECUTE\" status can become \"PAYMENT IN PROCESS\".	When the user's action is pending (e.g., OTP confirmation). Transaction can stay in this status for 24 hours since creation.	N
CHARGEBACK	Transaction type that allows customers to receive money back.	When requested by customer or merchant (manual process).	Y
REFUNDED	Only transactions in \"REFUND IN PROCESS\" status can become \"REFUNDED\".	When the provider confirms the refund.	Y
REFUND IN PROCESS	Only transactions in \"PAID\" status can become \"REFUND IN PROCESS\".	When Refund API is called and a response is received with \"REFUND IN PROCESS\" status.	N
ERROR	Only transactions in statuses: \"PENDING EXECUTE\", \"PAYMENT IN PROCESS\", \"PAYOUT IN PROCESS\" or \"REFUND IN PROCESS\" can become \"ERROR\".	Refers to the Errors list for possible errors.	Y

Note:

If you want a more detailed error message, please rely on the \"errorMsg\" field in the responses or webhook payload.

\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":[""],"id":"9c63deaa-2a41-40ba-94c0-12e74ce868ed"}},{"listen":"test","script":{"type":"text/javascript","exec":[""],"id":"f87235e7-b404-4746-a736-5b2a5e666cf5"}}],"_postman_id":"f8790b34-2cbb-4557-b664-e9be5fa45eaf"}],"id":"6959c487-f49f-4ed7-8fbe-0b751ff46c63","description":"

HTTP Response Code

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Code	Triggering Event
200	Successful Response
202	Successful / Accepted
400	Bad request, the given data is invalid, or additional data is required
401	unauthorized request
404	page not found
405	Method Not Allowed (GET/POST)
415	unsupported media type
422	Unprocessable content, data is required
429	Too many request attempt
500	Internal server error

You will not get Error codes if HTTPS response code is 200 or 202.

Error Codes and Messages

with http code (400, 404, 401, 405, 415)

Below is the list of possible error codes and the corresponding messages from Paybomb System

Format

{\n    \"message\": \"descriptive error message\",\n    \"code\": \"error_code\"\n}\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Code	Message	APIs that could generate the error code
Authentication_failed	Authorization header missing	All
already_in_process	Some Processing is running on this purchaseId	All
unsupported_media_type	Unsupported media type \"text/plain; charset=ISO-8859-1\" in request.	All
authentication_failed	Incorrect secret_key/Invalid Merchant Type	All
transaction_error	See the table below	See the table below

\"transaction_error\" Message List

All the Messages possible when \"transaction_error\" is in reponse:

Message	APIs that generate the error Message
Cvv_error	after executing callback_url
Expired card	after executing callback_url
expiry_date_error	after executing callback_url
Insufficient fund	after executing callback_url
Invalid card number	after executing callback_url
Issuing bank - do not honer	after executing callback_url
Picking card	after executing callback_url
Temp error - card blocked	after executing callback_url
Transaction declined - try again	after executing callback_url
PurchaseId Not found.	after executing callback_url
Only purchases that can be paid for can be initiated for payment.	after executing callback_url
Customer/Ip is Blocked	after executing callback_url
Client Ip could not be match with Merchant Ip	s2s calling
Invalid Card Information	s2s calling
Card is Blocked	s2s calling
Different Type of key used to create purchase and payment	s2s calling
You charges setting is in complete .Please Contact to Administrator.	s2s calling
Allowed Attempt for this Transaction has been consumed	s2s calling
Customer not allowed For transaction	s2s calling
Invalid Card Expiry(Valid Format:MM/YY) must be greater than current month/year	s2s calling
Customer profile is Blocked	s2s calling
Customer/Card not allowed for transaction	s2s calling
Allowed Limit for this card for particular time period has been consumed	create purchase
some Mandatory Parameter are missing	create purchase
Invalid_Parameter	create purchase
Invalid format of Date_of_Birth[allowed format: yyyy-mm-dd]	create purchase
Invalid Email Format	create purchase
Please submit Valid Alpha2 Country Code Ex:(AF,IN) in \\\"country\\\" parameter	create purchase
Please pass Valid State Code	create purchase
Please pass valid street address in \\\"street_address\\\" parameter	create purchase
Please pass valid city name in \\\"city\\\" parameter	create purchase
Please pass valid postal Code name in \\\"zip_code\\\" parameter	create purchase
You are not Allowed for Live Transaction	create purchase
Merchant Limit is not set	create purchase
Minimum amount is not set for this merchant	create purchase
Brand not found!	create purchase
Your charges setting is incomplete .Plese Contact to Administrator.	create purchase
Only “curr_name” currency is allowed	create purchase
Transaction amount must be equal or greater to minimum trans amount	create purchase
Transaction amount must not be greater to maximum trans amount	create purchase
This Purchase was already fully refunded.	`/refund/`
Previous Refund Request already in Process	`/refund/`
Max Time for Refund was elapsed.	`/refund/`
Refund can not be initiated .Please contact Administrator.	`/refund/`
Only Purchases with `status == (paid)` can be refunded.	`/refund/`
Only purchases that can be paid for can be cancelled.	`/cancel/`

","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":[""],"id":"f703b1fb-b943-498c-8702-205b986616c8"}},{"listen":"test","script":{"type":"text/javascript","exec":[""],"id":"5c9bcfb8-b49a-4f6a-b4a1-01cb51e2b65b"}}],"_postman_id":"6959c487-f49f-4ed7-8fbe-0b751ff46c63"},{"name":"Payment Methods","item":[{"name":"💳 Card Payments","item":[{"name":"Concepts","item":[],"id":"01819b93-c4c4-4e77-b7f4-b02d62c70a84","description":"

Paybomb Card Payments

Get started

Paybomb’s Server-to-Server (S2S) integration allows merchants to process card payments entirely from their backend systems. In this model, the client application or browser does not interact directly with Paybomb APIs. All sensitive payment operations are handled securely on the server.

This integration is recommended for merchants who require:

Full control over the checkout experience
\n
Reduced exposure of platform endpoints
\n
A secure and compliant payment architecture
\n

How it works

The S2S card payment flow follows a three-step process:

Create a purchase
Register the transaction and generate a unique purchaseId.
\n
Submit card details (S2S)
Send card and device details securely from your server.
\n
Handle callbacks and redirects
Complete the transaction using 2D or 3D Secure flows.
\n

This integration supports:

2D (non-3DS) transactions
\n
3D Secure Frictionless transactions
\n
3D Secure Challenge transactions
\n

Before you begin

Before starting the integration, ensure the following prerequisites are met:

You have received your API credentials from Paybomb
\n
Your server can make secure HTTPS requests
\n
You are PCI-DSS compliant for handling card data
\n
You have configured the following redirect URLs:
\n
- success_redirec
  \n
- pending_redirect
  \n
- failure_redirect
  \n
\n
You have a valid brand_id provided by Paybomb
\n

Create a New Payment Session

A payment session is created when a purchase is initialized in the Paybomb system. This session represents the starting point of a transaction and is required before submitting any payment details or initiating authentication flows.

Creating a payment session registers the transaction details, configures redirect URLs, and generates a unique identifier (purchaseId) that is used in all subsequent Server-to-Server (S2S) payment operations.

When to create a payment session

You must create a new payment session when:

A customer initiates a new checkout
\n
A new payment attempt is required
\n
You want to process a card payment using S2S integration
\n
You need to support 2D or 3D Secure payment flows
\n

Each payment session corresponds to one transaction attempt.

Payment Session Flow

Your server sends a request to the Create Purchase API with customer, product, and redirect details.
\n
Paybomb validates the request and creates a new payment session.
\n
A unique purchaseId is generated for the session.
\n
The payment session remains in the CREATED state until payment details are submitted.
\n
The purchaseId is used to continue the payment flow via S2S APIs.
\n

Card Payments

Card payments enable customers to pay online using debit or credit cards issued by card networks such as Visa, Mastercard, and others. During a card payment , the customer’s card details are submitted securely and sent through the payment processor , card network, and issuing bank to determine whether the transaction can be authorized.

Card payment checks include:

Card validity and available balance
\n
Risk and fraud assessment
\n
Authorization by the issuing bank
\n

Depending on the security requirements, region, and risk profile, a card payment can be processed as either:

2D (Non-3DS) payment
\n
3D Secure (3DS) payment
\n

2D (non-3DS) Payments

2D payments are standard card transactions that do not include an additional cardholder authentication step by issuing bank. Authorization is based on the card details and internal risk checks performed by the payment processor and issuer.

2D Payment Flow

The customer provide card details (card number, expiry, cvv)
\n
The transaction is authorized or declined by the issuing bank
\n
The customer is directly redirected to the final outcome URL
\n

Characteristics

Faster checkout experience
\n
Lower protection against fraud and chargebacks
\n
No callback URL generated
\n
No 3D Secure authentication
\n

Typical Use Case

Low-risk transactions
\n
Trusted customers
\n
Regions or scenarios where 3DS is not mandatory
\n

3D Secure (3DS) Payments

3D secure (3DS) Payments add an extra layer of security by requiring the cardholder to be authenticated by issuing bank. This helps reduce fraud and protects merchants against certain types of chargebacks.

3DS Payment Flow

The transaction is evaluated by the card network and issuing bank
\n
Based on risk assessment, the transaction proceeds through either a Frictionless or Challenge flow
\n
After authentication, the transaction is authorized or declined
\n
The customer is redirected to the appropriate URL
\n

3DS Authentication Flows

3D Secure Challenge Flow

The customer is redirected to the issuer’s ACS (Access Control Server)
\n
The cardholder must authenticate (OTP, biometric, or password)
\n
After authentication, the customer is redirected to the appropriate URL
\n

3DS payments provide higher security, better fraud prevention, and improved compliance with regulatory requirements such as PSD2 (Second Payment Service Directive).

3D Secure Frictionless Flow

No user interaction is required
\n
Authentication is completed automatically in the background
\n
The customer is directly redirected to the appropriate URL
\n

2D vs 3D Secure - Comparison Table

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Feature	2D (Non-3DS) Payments	3D Secure (3DS) Payments
Cardholder authentication	Not required	Required (Frictionless or Challenge)
User interaction	Not required	Required only in Challenge flow
Security level	Standard	High
Fraud protection	Limited	Strong
Chargeback liability shift	No	Yes (subject to scheme rules)
Callback URL	Not generated	Generated when authentication is required
Redirect handling	Direct redirect to final URL	Redirect after authentication
Checkout speed	Faster	Slightly slower (Challenge flow only)
Regulatory compliance	Not always sufficient	Helps meet PSD2 and similar regulations
Typical use case	Low-risk transactions	Medium to high-risk transactions

Required configuration

To successfully create a payment session, the following must be provided:

Customer information (name, email, location)
\n
Purchase details (currency and products)
\n
A valid brand_id
\n
Redirect URLs to handle the final transaction outcome:
\n
- success_redirect
  \n
- pending_redirect
  \n
- failure_redirect
  \n
\n

These redirect URLs are mandatory and are used later during 2D or 3D Secure flows.

Redirect Handling

After successful background authentication, the user is redirected to one of the following URLs, which must be configured during the Purchase Creation step:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Redirect URL	Description
success_redirect	Payment completed successfully
pending_redirect	Payment is still under processing
failure_redirect	Payment failed or was declined

The final redirect depends on the authorization and authentication outcome returned by the issuer.

API Used for Card Payment

| POST /api/v1/purchases |

Step 1: Transaction Initiation – Create a Purchase

Overview

To begin a transaction, a Purchase must first be created in the system. This is done by initiating a purchase request that registers all required transaction details and prepares the system for further processing.

This step applies equally to both 2D and non-2D transactions and follows the same flow regardless of transaction type.

Purchase Creation Process

A purchase is initiated by sending a POST request to the purchase creation endpoint ({baseURL}/purchase/).
\n
During this step, the system validates the request and creates a Purchase record.
\n
Once the Purchase is successfully created, the system generates a unique purchaseId, which is required for subsequent server-to-server operations.
\n

Mandatory Redirect URLs

To successfully create a Purchase, the following redirect URLs must be defined and must contain valid URLs:

success_redirect
Redirects the customer after a successful transaction.
\n
pending_redirect
Redirects the customer when the transaction remains in a pending or processing state.
\n
failure_redirect
Redirects the customer if the transaction fails.
\n

merchantRef (Merchant Reference)

Although not mandatory, the merchantRef parameter is strongly recommended for all merchants.

Purpose and Benefits

Prevention of Duplicate Transactions
\n
- merchantRef acts as a unique merchant-defined reference.
  \n
- If a subsequent purchase request is sent using the same merchantRef, the system identifies it as a duplicate and prevents accidental repeat transactions.
  \n
\n
Transaction Retrieval and Recovery
\n
- If the purchase creation response times out or the purchaseId is not received,
  the merchant can use merchantRef to retrieve the corresponding transaction details.
  \n
- This ensures reliable tracking and reconciliation even when immediate responses are unavailable.
  \n
\n

System Behavior Without merchantRef

If merchantRef is not provided, the platform automatically assigns an internal purchaseId.
\n
This internally generated purchaseId then becomes the sole reference for that transaction.
\n

Purchase Creation Outcome

On successful creation of a Purchase:
\n
- The system returns a purchaseId.
  \n
- This purchaseId uniquely identifies the transaction within the platform.
  \n
\n

Step 2: Server-to-Server (S2S) Processing

After receiving the purchaseId, merchants must proceed with the server-to-server (S2S) call using the following pattern:

This call is required to continue processing the transaction securely on the server side.

| p/{purchaseId}/?s2s=true |

Step 3: Transaction Flows After Calling callback_url

After the callback URL is invoked, the transaction can proceed through one of the following three flows:

3D Secure Challenge Flow

The user is redirected to the ACS (Access Control Server) page of the issuing bank.
\n
The cardholder is required to complete authentication (e.g., OTP, biometric, or password).
\n
After successful or failed authentication, the user is redirected to one of the URLs configured during the Purchase Creation API:
\n
- Success_redirect
  \n
- Pending_redirect
  \n
- failure_redirect
  \n
\n

The final redirect depends on the transaction outcome.

3D Secure Frictionless Flow

The 3D Secure Frictionless Flow is a streamlined authentication process where the cardholder does not need to perform any additional action. The authentication is completed automatically in the background based on risk assessment performed by the card network and the issuing bank.

This flow is designed to deliver a fast and seamless checkout experience while still complying with 3D Secure regulations.

When Frictionless Flow Occurs

A transaction may qualify for the frictionless flow when:

The transaction amount is considered low risk
\n
The issuing bank trusts the merchant and transaction context
\n
Accurate device and browser information is provided
\n
The cardholder has a positive transaction history
\n

Note: The final decision to apply frictionless authentication is made solely by the issuing bank.

Important:

Calling the callback_url is mandatory for all transactions returning a 202 response.
\n
All redirect URLs must be predefined during the Purchase Creation step.
\n
Merchants should ensure proper handling of all three redirect outcomes to deliver a seamless user experience.
\n

Operational Flow

The merchant submits the card payment request using the Server-to-Server (S2S) API.
\n
Paybomb sends the transaction details to the card network and issuing bank for 3D Secure evaluation.
\n
The issuing bank determines that no challenge is required based on:
\n
- Cardholder risk profile
  \n
- Transaction amount
  \n
- Device and browser data
  \n
- Merchant trust level
  \n
\n
Authentication is successfully completed in the background without redirecting the user to an authentication (ACS) page.
\n
Once authentication and authorization are completed, the user is automatically redirected to the appropriate URL configured during the Purchase Creation API.
\n

HTTP Response Codes

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Code	Triggering Event
200	Request processed successfully
202	Request accepted and processing is pending
400	Bad request – invalid data provided or required data is missing
401	Unauthorized request – invalid or missing authentication credentials
404	Resource or page not found
405	Method not allowed (unsupported HTTP method such as GET or POST)
415	Unsupported media type
422	Unprocessable content – required data is missing or invalid
429	Too many requests – rate limit exceeded
500	Internal server error

Please see the Status Code section for further details.

If the response code is 202, upon receiving the response body, redirect the customer to the callback_url provided in the response.

If the card requires 3D Secure verification, the user will be redirected to a verification or challenge screen by the card issuing bank. After successful user verification, the user will be redirected to the success URL provided in the /purchase API from Step 1.

If, for any reason, the transaction is unsuccessful, the user will be redirected the failure URL provided in the /purchase API from Step 1.

\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"4d4fe764-bc73-4703-8dc1-d4dcfb65f948"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"42faccbf-d26f-4957-affe-308628f4e63b"}}],"_postman_id":"01819b93-c4c4-4e77-b7f4-b02d62c70a84"},{"name":"APIs","item":[{"name":"Purchase","id":"3e401596-9ca1-4640-89aa-7469f8dba264","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[]},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"email\": \"example@paybomb.tech\",\r\n \"country\": \"IN\",\r\n \"city\": \"123\",\r\n \"stateCode\": \"ca\",\r\n \"street_address\": \"test test\",\r\n \"zip_code\": \"234567\",\r\n \"phone\": \"+91 9999999999\"\r\n },\r\n \"purchase\": {\r\n \"products\": [\r\n {\r\n \"name\": \"dk\",\r\n \"price\": \"10\"\r\n }\r\n ]\r\n },\r\n \"status\": \"created\",\r\n \"brand_id\": \"bd69e8a5-adcf-40de-9e43-2b87cb129a5e \",\r\n \"merchantRef\": \"d9db7ec0-f94c-4a9d-8883-54c19c222d81\",\r\n \"success_redirect\": \"https://your.success.redirect.com\",\r\n \"pending_redirect\": \"https://your.pending.redirect.com\",\r\n \"failure_redirect\": \"https://your.failure.redirect.com\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/purchases","description":"

To Initiate a payment, the very first call to make is /purchases with the required data in the request body.

To generate a Purchase, you are required to provide the Brand ID (in the request body) and API key (in the header) Both can be located in the Dashboard section of your merchant account login.

The request body structure is shown on the request body of the example request shown here.

The following (see table below) are the mandatory parameters that are required to create a purchase request.

Mandatory parameters in the request body:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Notes
client.email	The customer's email.
client.city	The customer's city.
client.country	ISO-3166 Country Code. Must be upper case. Example “SG” (Alpha2)
client.stateCode	Example “AL”, “XZ”. Must be in upper case.
Client.street_address	The customer's address.
client.zip_code	The customer's ZIP or postal code. If country=US, zip format must be NNNNN or NNNNN-NNNN.
purchase.currency	ISO 4217 code for currency you want to send the transaction in. Please note, the currency has to be enabled by the account manager for your account.
purchase.products	An object which contains the list of products which the customer is buying.
purchase.products.name	The name of the product.
purchase.products.price	Price in decimal format. example 1: EUR 5 , should be sent as 5.00 example 2: USD 10 and 37 cents , should be sent as 10.37
brand_id	Obtain from Dashboard section of your merchant account login.
success_redirect	URL to send the user if the transactions is successful.
pending_redirect	URL to send the user if the transactions is in pending.
failure_redirect	URL to send the user if the transactions is unsuccessful.

Essential Optional Parameters

merchantRef

The merchantRef parameter, although not mandatory, is strongly advised for merchants to specify. Its inclusion offers two significant advantages for the merchant:

Prevention of Duplicate Requests: When a merchantRef is utilized, it acts as a unique identifier. This means that if a second purchase request is made using the same merchantRef (reference number), the system will recognize it and prevent duplicate transactions from occurring. This prevents unintended or duplicate purchases.
\n
Facilitation of Transaction Retrieval: In situations where the response from the initial purchase request times out or the 'purchaseId' isn't received, having the merchantRef allows the merchant to retrieve detailed transaction information. This ensures they can track and access the specific purchase details related to that reference, even if the immediate response was not received.
\n

However, if the merchant does not specify the 'merchantRef' parameter, the platform will automatically assign and use an internal 'purchaseId' as a reference for that transaction.

Upon successul create on a Purchase you'd get a \"purchaseId\" . Use this ID for the next step in Server to server call by calling p/{purchaseId}/?s2s=true .

paymentMethod

The paymentMethod parameter identifies which payment solution merchant wants to use to perform a transaction. If parameter is provided, than Paybomb will perform direct payment with the selected payment method instead of loading Paybomb URL.

Errors

If there are any errors then it'll be in the format of :

{\n    \"message\": \"descriptive error message\",\n    \"code\": \"error_code\"\n}\n\n

Possible Error Messages

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Error Messages
Allowed Limit for this card for particular time period has been consumed
some Mandatory Parameter are missing
Invalid format of Date_of_Birth [allowed format: yyyy-mm-dd]
Invalid Email Format
Please submit Valid Alpha2 Country Code Ex:(AF,IN) in \\\"country\\\" parameter
Please pass Valid State Code
Please pass valid street address in \\\"street_address\\\" parameter
Please pass valid city name in \\\"city\\\" parameter
Please pass valid postal Code name in \\\"zip_code\\\" parameter
You are not Allowed for Live Transaction
Merchant Limit is not set
Minimum amount is not set for this merchant
Brand not found !
Your charges setting is incomplete .Plese Contact to Administrator.
Only {{currencyCode}} currency is allowed.
Transaction amount must be equal or greater to minimum trans amount
Invalid_Parameter You'd usually get it when one or more mandatory parameters are not present in the request.

","urlObject":{"path":["purchases"],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"8589dabd-2b5f-4d23-a17c-0577ca3449b1","name":"Purchase","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text","disabled":true}],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"email\": \"example@paybomb.tech\",\r\n \"country\": \"IN\",\r\n \"city\": \"123\",\r\n \"stateCode\": \"ca\",\r\n \"street_address\": \"test test\",\r\n \"zip_code\": \"234567\",\r\n \"phone\": \"9999999999\"\r\n },\r\n \"purchase\": {\r\n \"currency\": \"USD\",\r\n \"products\": [\r\n {\r\n \"name\": \"product name\",\r\n \"price\": \"10\"\r\n }\r\n ]\r\n },\r\n \"merchantRef\": \"d9db7ec0-f94c-4a9d-8883-54c19c222d81\",\r\n \"status\": \"created\",\r\n \"brand_id\": \"bd69e8a5-adcf-40de-9e43-2b87cb129a5e \",\r\n \"success_redirect\": \"https://your.success.redirect.com\",\r\n \"pending_redirect\": \"https://your.pending.redirect.com\",\r\n \"failure_redirect\": \"https://your.failure.redirect.com\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/purchases"},"status":"Accepted","code":202,"_postman_previewlanguage":"json","header":[{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"1; mode=block"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"X-Frame-Options","value":"DENY"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Date","value":"Thu, 13 Jul 2023 17:22:14 GMT"},{"key":"Keep-Alive","value":"timeout=60"},{"key":"Connection","value":"keep-alive"}],"cookie":[],"responseTime":null,"body":"{\n \"purchaseId\": \"64b032c3c6dccf7d329d9e7e\",\n \"client\": {\n \"bank_account\": \"\",\n \"bank_code\": \"\",\n \"email\": \"dev@paybomb.tech\",\n \"phone\": \"\",\n \"full_name\": \"\",\n \"date_of_birth\": \"\",\n \"personal_code\": \"\",\n \"street_address\": \"test test\",\n \"country\": \"IN\",\n \"city\": \"123\",\n \"zip_code\": \"234567\",\n \"shipping_street_address\": \"\",\n \"shipping_country\": \"\",\n \"shipping_city\": \"\",\n \"shipping_zip_code\": \"\",\n \"cc\": [],\n \"bcc\": [],\n \"legal_name\": \"\",\n \"brand_name\": \"\",\n \"registration_number\": \"\",\n \"tax_number\": \"\",\n \"stateCode\": \"ca\"\n },\n \"updated_on\": 1689268934,\n \"type\": \"purchase\",\n \"force_recurring\": false,\n \"created_on\": 1689268934,\n \"purchase\": {\n \"currency\": \"USD\",\n \"products\": [\n {\n \"name\": \"dk\",\n \"quantity\": 1,\n \"price\": 10,\n \"discount\": 0,\n \"tax_percent\": \"0.00\"\n }\n ],\n \"total\": 10,\n \"language\": \"en\",\n \"notes\": \"\",\n \"debt\": 0,\n \"total_formatted\": 1,\n \"request_client_details\": [],\n \"timezone\": \"America/Edmonton\",\n \"email_message\": \"\"\n },\n \"issuer_details\": {\n \"website\": \"\",\n \"legal_street_address\": \"\",\n \"legal_country\": \"\",\n \"legal_city\": \"\",\n \"legal_zip_code\": \"\",\n \"bank_accounts\": [\n {\n \"bank_account\": \"\",\n \"bank_code\": \"\"\n }\n ],\n \"legal_name\": \"shoes\",\n \"brand_name\": \"shoes\",\n \"registration_number\": \"\",\n \"tax_number\": \"\"\n },\n \"transaction_data\": {\n \"payment_method\": \"\",\n \"flow\": \"payform\",\n \"extra\": {},\n \"country\": \"\",\n \"attempts\": []\n },\n \"status\": \"CREATED\",\n \"status_history\": [\n {\n \"status\": \"created\",\n \"timestamp\": 1689268934\n }\n ],\n \"is_test\": false,\n \"brand_id\": \"bd69e8a5-adcf-40de-9e43-2b87cb129a5e\",\n \"is_recurring_token\": false,\n \"reference_generated\": \"PS161\",\n \"merchantRef\":\"d9db7ec0-f94c-4a9d-8883-54c19c222d81\",\n \"issued\": \"2023-07-13\",\n \"due\": 1689268934,\n \"refund_upto\": 0,\n \"cc_descriptor\": \"\",\n \"refund_availability\": \"NONE\",\n \"refundable_amount\": 0,\n \"success_redirect\": \"https://your.success.redirect.com\",\n \"failure_redirect\": \"https://your.failure.redirect.com\",\n \"cancel_redirect\": \"\",\n \"success_callback\": \"\",\n \"platform\": \"API\",\n \"created_from_ip\": \"149.86.53.48\",\n \"checkout_url\": \"http://18.214.100.20/payments/64b032c3c6dccf7d329d9e7e/\",\n \"direct_post_url\": \"http://18.214.100.20/api/v1/p/64b032c3c6dccf7d329d9e7e/\"\n}"}],"_postman_id":"3e401596-9ca1-4640-89aa-7469f8dba264"},{"name":"S2S","id":"6b16f3fb-317e-4190-92ad-bab88adf2bb6","protocolProfileBehavior":{"disableUrlEncoding":false,"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"cardholder_name\": \"dk\",\r\n \"card_number\": \"4111111111111111\",\r\n \"expires\": \"10/23\",\r\n \"cvc\": \"345\",\r\n \"remember_card\": \"on\",\r\n \"remote_ip\": \"157.38.242.7\",\r\n \"user_agent\": \"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36\",\r\n \"accept_header\": \"text/html\",\r\n \"language\": \"en-US\",\r\n \"java_enabled\": false,\r\n \"javascript_enabled\": true,\r\n \"color_depth\": 24,\r\n \"utc_offset\": 0,\r\n \"screen_width\": 1920,\r\n \"screen_height\": 1080\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/p/64bff4fff63e36669499e9c8/?s2s=true","description":"

This API would be the 2nd in sequence to call if the call to /purchases/ was successful in step 1. and you want to do the transaction via Server-to-Server mode.

The request body would contain the details of the card that's to be transacted upon.

Mandatory parameters in request body:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Notes
remote_ip	IP address of the customer’s device used for transaction. Helps in fraud checks and risk scoring. Ex- 157.38.242.7
user_agent	Full browser and operating system details captured from HTTP header. EX- Chrome/5.0 (X11; Linux x86_64)
accept_header	Browser’s accepted content types (from HTTP header). Used for validating request origin and device info. EX- text/html

Note:
If you want to use token_reference for doing a card transaction, please have a look at Network Tokenisation Section.

Essential parameters in request body:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Notes
cardholder_name	Name of the cardholder
card_number	The card numbers Must be 10-20 characters.
expires	must be greater than the current month/year.
cvc	3 or 4 digit

**
Other optional parameters in request body:**

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Notes
language	Preferred language of the user’s browser . EX - en-US
java_enabled	Indicates if Java is enabled in the browser. Helps PSPs in device profiling. Ex- true/false
javascript_enabled	Indicates if JavaScript is enabled in the client browser. Used for 3DS or risk-based checks. Ex- true
color_depth	Bit depth of the display screen. Ex- 24
utc_offset	Difference in minutes between local time and UTC. Used for location and timezone checks. Ex- 330
screen_width	Width of the device screen in pixels. Used in device profiling. Ex- 1920
screen_height	Height of the device screen in pixels. Ex- 1080

Successful Response

If all the details are correct you'll get a 202 response with staus as Pending

{\n    \"status\": \"pending\",\n    \"callback_url\": \"https://app.paybomb.tech/payment/63bd0bf80fb42a076e8a4dd1/\",\n    \"method\": \"GET\"\n}\n\n

If the response code is 202, after receiving the response body, direct the customer to the callback_url provided in the response.

Errors

If there are any errors then it'll be in the format of :

{\n    \"message\": \"descriptive error message\",\n    \"code\": \"error_code\"\n}\n\n

Please see the Status Code section for further details.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Error Messages
Client Ip could not be matched with Merchant Ip
Invalid Card Information
Card is Blocked
Different Type of key used to create purchase and payment
You charges setting is incomplete .Plese Contact to adminstrartor.
Allowed Attempt for this Transaction has been consumed
Invalid Card Expiry(Valid Format:MM/YY) must be greator than current month/year
Customer profile is Blocked
Customer/Card not allowed for transaction

","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"90ea93fb-a535-4243-bd42-deba195cc075","id":"90ea93fb-a535-4243-bd42-deba195cc075","name":"APIs","type":"folder"}},"urlObject":{"path":["p","64bff4fff63e36669499e9c8",""],"host":["https://app.paybomb.tech/api/v1"],"query":[{"key":"s2s","value":"true"}],"variable":[]}},"response":[{"id":"7ba2f3c1-f00b-4a98-8b6f-b88e67773100","name":"Success","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"cardholder_name\": \"dk\",\r\n \"card_number\": \"411111111111111\",\r\n \"expires\": \"10/23\",\r\n \"cvc\": \"345\",\r\n \"remember_card\": \"on\",\r\n \"remote_ip\": \"157.38.242.7\",\r\n \"user_agent\": \"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36\",\r\n \"accept_header\": \"text/html\",\r\n \"language\": \"en-US\",\r\n \"java_enabled\": false,\r\n \"javascript_enabled\": true,\r\n \"color_depth\": 24,\r\n \"utc_offset\": 0,\r\n \"screen_width\": 1920,\r\n \"screen_height\": 1080\r\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://app.paybomb.tech/api/v1/p/64bff4fff63e36669499e9c8/?s2s=true","host":["https://app.paybomb.tech/api/v1"],"path":["p","64bff4fff63e36669499e9c8",""],"query":[{"key":"s2s","value":"true"}]}},"status":"Accepted","code":202,"_postman_previewlanguage":"json","header":[{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"1; mode=block"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"X-Frame-Options","value":"DENY"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Date","value":"Thu, 13 Jul 2023 17:31:55 GMT"},{"key":"Keep-Alive","value":"timeout=60"},{"key":"Connection","value":"keep-alive"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": \"pending\",\n \"callback_url\": \"http://18.214.100.20/api/v1/payment/64b034ecc6dccf7d329d9eb3/\",\n \"method\": \"GET\"\n}"},{"id":"8c9db494-1c42-4bb3-af19-5249bdeeb780","name":"Failure","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"cardholder_name\": \"dk\",\r\n \"card_number\": \"4111111111111111\",\r\n \"expires\": \"10/23\",\r\n \"cvc\": \"345\",\r\n \"remember_card\": \"on\",\r\n \"remote_ip\": \"157.38.242.7\",\r\n \"user_agent\": \"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36\",\r\n \"accept_header\": \"text/html\",\r\n \"language\": \"en-US\",\r\n \"java_enabled\": false,\r\n \"javascript_enabled\": true,\r\n \"color_depth\": 24,\r\n \"utc_offset\": 0,\r\n \"screen_width\": 1920,\r\n \"screen_height\": 1080\r\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://app.paybomb.tech/api/v1/p/64bff4fff63e36669499e9c8/?s2s=true","host":["https://app.paybomb.tech/api/v1"],"path":["p","64bff4fff63e36669499e9c8",""],"query":[{"key":"s2s","value":"true"}]}},"status":"Unauthorized","code":401,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Tue, 06 Jan 2026 05:57:10 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"X-Frame-Options","value":"ALLOW-FROM *"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"x-session-id","value":"cc434220-0bcd-42c7-9078-53503b81a221"},{"key":"Vary","value":"Origin"},{"key":"Vary","value":"Access-Control-Request-Method"},{"key":"Vary","value":"Access-Control-Request-Headers"},{"key":"Server","value":"cloudflare"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"0"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"Strict-Transport-Security","value":"max-age=31536000 ; includeSubDomains"},{"key":"X-Cache","value":"Error from cloudfront"},{"key":"Via","value":"1.1 9bce423254194c16408d5cf7234126e2.cloudfront.net (CloudFront)"},{"key":"X-Amz-Cf-Pop","value":"IAD61-P10"},{"key":"X-Amz-Cf-Id","value":"FgTt6KEGIk0CH79DQDOvB1tYb1pGfaz0ryIVmQ0CCpDShyhsJGuAkA=="},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=9SnHJOEjnd1y7hArGsRLWmrk8H9ExaiR%2Fc%2BQMWhAvHlNPYCNEjS60wTjIyODXpca0ZD9%2BalkhLJ63boMGg%2B8iI6eFtXfW%2BxwGaBP1p1ZcwpA\"}]}"},{"key":"CF-RAY","value":"9b98f9f4684505e7-IAD"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"Authorization header missing\",\n \"code\": \"authentication_failed\"\n}"}],"_postman_id":"6b16f3fb-317e-4190-92ad-bab88adf2bb6"},{"name":"Payment (To be initiated From client browser)","id":"4e9741b2-5317-4484-a5ec-0b3302691ffe","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"{{Production}}/payment/64bff12bf63e36669499e97d/","description":"

This is the callback URL that is in the response object ofthe Server-to-Server Call

When this URL is called from the end user's browser, the user would be redirected to the success_redirect or failure_redirect URL given by the merchant at the time of create purchase

When this URL is called from the end user's browser, if card is 3DS enrolled, the user user will be redirect to a verification screen or challenge by the issuing bank and upon successful user verification, the user would be redictected to the success URL given in /purchases API .

If for some reason the transactions is unsuccessful, the user will be redirect to failure URL given in /purchases API API .

This API tells you about all the details of a purchase, including its history

Mandatory

you need to pass the PurchaseID in the API URL

Possible Value of Status

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Notes
created	When Purchase order is created.
paid	Transaction Successful
payment_in_process	Payment is under Processing
chargeback	Payment is chargeback state
refund_in_process	Refund is under Processing.
expired	Purchase has Expired.
overdue	Purchase is Overdued.
cancelled	Purchase is cancelled.
error	Transaction has Failed.
refunded	Payment is refunded

Response Examples

In the response examples you can see instances of both Paid and Error Status purchases.

Error Details

If there are any issues on the Purchase you can get more details from the transaction_data.attempts.error attribute of the response object

Errors

If there are any errors then it'll be in the format of :

{\n    \"message\": \"descriptive error message\",\n    \"code\": \"error_code\"\n}\n\n

Please see the Status Code section for further details.

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"90ea93fb-a535-4243-bd42-deba195cc075","id":"90ea93fb-a535-4243-bd42-deba195cc075","name":"APIs","type":"folder"}},"urlObject":{"path":["purchases","64bff12bf63e36669499e97d",""],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"c7448c9d-a384-4f03-8db4-117f5b78c72a","name":"Purchases-error","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"url":"http://18.214.100.20/api/v1/purchases/64bfd7c9f63e36669499e779/"},"status":"Accepted","code":202,"_postman_previewlanguage":"json","header":[{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"1; mode=block"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"X-Frame-Options","value":"DENY"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Date","value":"Tue, 25 Jul 2023 15:44:06 GMT"},{"key":"Keep-Alive","value":"timeout=60"},{"key":"Connection","value":"keep-alive"}],"cookie":[],"responseTime":null,"body":"{\n \"purchaseId\": \"64bfd7c9f63e36669499e779\",\n \"client\": {\n \"bank_account\": \"\",\n \"bank_code\": \"\",\n \"email\": \"example@paybomb.tech\",\n \"phone\": \"\",\n \"full_name\": \"\",\n \"date_of_birth\": \"\",\n \"personal_code\": \"\",\n \"street_address\": \"test test\",\n \"country\": \"IN\",\n \"city\": \"123\",\n \"zip_code\": \"234567\",\n \"shipping_street_address\": \"\",\n \"shipping_country\": \"\",\n \"shipping_city\": \"\",\n \"shipping_zip_code\": \"\",\n \"cc\": [],\n \"bcc\": [],\n \"legal_name\": \"\",\n \"brand_name\": \"\",\n \"registration_number\": \"\",\n \"tax_number\": \"\",\n \"stateCode\": \"ca\"\n },\n \"updated_on\": 1690294251,\n \"type\": \"purchase\",\n \"force_recurring\": false,\n \"created_on\": 1690294220,\n \"purchase\": {\n \"currency\": \"USD\",\n \"products\": [\n {\n \"name\": \"dk\",\n \"quantity\": 1,\n \"price\": 100,\n \"discount\": 0,\n \"tax_percent\": \"0.00\"\n }\n ],\n \"total\": 100,\n \"language\": \"en\",\n \"notes\": \"\",\n \"debt\": 0,\n \"total_formatted\": 1,\n \"request_client_details\": [],\n \"timezone\": \"America/Edmonton\",\n \"email_message\": \"\"\n },\n \"issuer_details\": {\n \"website\": \"\",\n \"legal_street_address\": \"\",\n \"legal_country\": \"\",\n \"legal_city\": \"\",\n \"legal_zip_code\": \"\",\n \"bank_accounts\": [\n {\n \"bank_account\": \"\",\n \"bank_code\": \"\"\n }\n ],\n \"legal_name\": \"shoes\",\n \"brand_name\": \"shoes\",\n \"registration_number\": \"\",\n \"tax_number\": \"\"\n },\n \"transaction_data\": {\n \"payment_method\": \"\",\n \"flow\": \"payform\",\n \"extra\": {\n \"expiry_month\": \"10\",\n \"amount\": 100,\n \"card_issuer\": \"1-800-432-3117\",\n \"masked_pan\": \"411111XXXXXX1111\",\n \"card_brand\": \"VISA\",\n \"card_issuer_country\": \"US\",\n \"cardholder_name\": \"dk\",\n \"expiry_year\": \"23\"\n },\n \"country\": \"\",\n \"attempts\": [\n {\n \"client_ip\": \"149.86.53.48\",\n \"type\": \"execute\",\n \"payment_method\": \"VISA\",\n \"flow\": \"payform\",\n \"successful\": false,\n \"country\": \"US\",\n \"processing_time\": 1690294279,\n \"extra\": {\n \"expiry_month\": \"10\",\n \"amount\": 100,\n \"card_issuer\": \"1-800-432-3117\",\n \"masked_pan\": \"411111XXXXXX1111\",\n \"card_brand\": \"VISA\",\n \"card_issuer_country\": \"US\",\n \"cardholder_name\": \"dk\",\n \"expiry_year\": \"23\"\n },\n \"error\": {\n \"message\": \"Transaction Failed\",\n \"code\": \"transaction_error\"\n }\n }\n ]\n },\n \"status\": \"ERROR\",\n \"status_history\": [\n {\n \"status\": \"created\",\n \"timestamp\": 1690294220\n },\n {\n \"status\": \"pending_execute\",\n \"timestamp\": 1690294251\n },\n {\n \"status\": \"error\",\n \"timestamp\": 1690294299\n },\n {\n \"status\": \"viewed\",\n \"timestamp\": 1690294382\n }\n ],\n \"viewedOn\": 1690299845,\n \"is_test\": false,\n \"brand_id\": \"bd69e8a5-adcf-40de-9e43-2b87cb129a5e\",\n \"send_receipt\": false,\n \"is_recurring_token\": false,\n \"skip_capture\": false,\n \"reference_generated\": \"PS188\",\n \"issued\": \"2023-07-25\",\n \"due\": 1690294220,\n \"refund_upto\": 0,\n \"cc_descriptor\": \"\",\n \"refund_availability\": \"NONE\",\n \"refundable_amount\": 0,\n \"success_redirect\": \"https://google.com\",\n \"failure_redirect\": \"https://yahoo.com\",\n \"cancel_redirect\": \"\",\n \"success_callback\": \"\",\n \"platform\": \"API\",\n \"created_from_ip\": \"149.86.53.48\",\n \"checkout_url\": \"http://18.214.100.20/payments/64bfd7c9f63e36669499e779/\",\n \"direct_post_url\": \"http://18.214.100.20/api/v1/p/64bfd7c9f63e36669499e779/\"\n}"},{"id":"1fa60c14-f85b-4b06-9e89-eda4288033b0","name":"Purchases - success","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"url":"http://18.214.100.20/api/v1/purchases/64bfdb7df63e36669499e82f/"},"status":"Accepted","code":202,"_postman_previewlanguage":"json","header":[{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"1; mode=block"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"X-Frame-Options","value":"DENY"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Date","value":"Tue, 25 Jul 2023 15:45:29 GMT"},{"key":"Keep-Alive","value":"timeout=60"},{"key":"Connection","value":"keep-alive"}],"cookie":[],"responseTime":null,"body":"{\n \"purchaseId\": \"64bfdb7df63e36669499e82f\",\n \"client\": {\n \"bank_account\": \"\",\n \"bank_code\": \"\",\n \"email\": \"example@paybomb.tech\",\n \"phone\": \"\",\n \"full_name\": \"\",\n \"date_of_birth\": \"\",\n \"personal_code\": \"\",\n \"street_address\": \"test test\",\n \"country\": \"IN\",\n \"city\": \"123\",\n \"zip_code\": \"234567\",\n \"shipping_street_address\": \"\",\n \"shipping_country\": \"\",\n \"shipping_city\": \"\",\n \"shipping_zip_code\": \"\",\n \"cc\": [],\n \"bcc\": [],\n \"legal_name\": \"\",\n \"brand_name\": \"\",\n \"registration_number\": \"\",\n \"tax_number\": \"\",\n \"stateCode\": \"ca\"\n },\n \"updated_on\": 1690296521,\n \"type\": \"purchase\",\n \"force_recurring\": false,\n \"created_on\": 1690295168,\n \"purchase\": {\n \"currency\": \"USD\",\n \"products\": [\n {\n \"name\": \"dk\",\n \"quantity\": 1,\n \"price\": 9,\n \"discount\": 0,\n \"tax_percent\": \"0.00\"\n }\n ],\n \"total\": 9,\n \"language\": \"en\",\n \"notes\": \"\",\n \"debt\": 0,\n \"total_formatted\": 1,\n \"request_client_details\": [],\n \"timezone\": \"America/Edmonton\",\n \"email_message\": \"\"\n },\n \"payment\": {\n \"is_outgoing\": false,\n \"payment_type\": \"PURCHASE\",\n \"amount\": 9,\n \"currency\": \"USD\",\n \"net_amount\": 9,\n \"fee_amount\": 10.2591,\n \"pending_amount\": 0,\n \"pending_unfreeze_on\": null,\n \"description\": \"\",\n \"paid_on\": 1690295205,\n \"remote_paid_on\": 1690295205\n },\n \"issuer_details\": {\n \"website\": \"\",\n \"legal_street_address\": \"\",\n \"legal_country\": \"\",\n \"legal_city\": \"\",\n \"legal_zip_code\": \"\",\n \"bank_accounts\": [\n {\n \"bank_account\": \"\",\n \"bank_code\": \"\"\n }\n ],\n \"legal_name\": \"shoes\",\n \"brand_name\": \"shoes\",\n \"registration_number\": \"\",\n \"tax_number\": \"\"\n },\n \"transaction_data\": {\n \"payment_method\": \"\",\n \"flow\": \"payform\",\n \"extra\": {\n \"expiry_month\": \"10\",\n \"amount\": 9,\n \"card_issuer\": \"1-800-432-3117\",\n \"masked_pan\": \"411111XXXXXX1111\",\n \"card_brand\": \"VISA\",\n \"card_issuer_country\": \"US\",\n \"cardholder_name\": \"dk\",\n \"expiry_year\": \"23\"\n },\n \"country\": \"\",\n \"attempts\": [\n {\n \"client_ip\": \"149.86.53.48\",\n \"type\": \"execute\",\n \"payment_method\": \"VISA\",\n \"flow\": \"payform\",\n \"successful\": true,\n \"country\": \"US\",\n \"processing_time\": 1690295205,\n \"extra\": {\n \"expiry_month\": \"10\",\n \"amount\": 9,\n \"card_issuer\": \"1-800-432-3117\",\n \"masked_pan\": \"411111XXXXXX1111\",\n \"card_brand\": \"VISA\",\n \"card_issuer_country\": \"US\",\n \"cardholder_name\": \"dk\",\n \"expiry_year\": \"23\"\n }\n }\n ]\n },\n \"status\": \"PAID\",\n \"status_history\": [\n {\n \"status\": \"created\",\n \"timestamp\": 1690295168\n },\n {\n \"status\": \"pending_execute\",\n \"timestamp\": 1690295193\n },\n {\n \"status\": \"payment_in_process\",\n \"timestamp\": 1690295205\n },\n {\n \"status\": \"paid\",\n \"timestamp\": 1690296521\n },\n {\n \"status\": \"viewed\",\n \"timestamp\": 1690299929\n }\n ],\n \"viewedOn\": 1690299929,\n \"is_test\": false,\n \"brand_id\": \"bd69e8a5-adcf-40de-9e43-2b87cb129a5e\",\n \"merchantRef\":\"d9db7ec0-f94c-4a9d-8883-54c19c222d81\",\n \"send_receipt\": false,\n \"is_recurring_token\": false,\n \"skip_capture\": false,\n \"reference_generated\": \"PS192\",\n \"issued\": \"2023-07-25\",\n \"due\": 1690295168,\n \"refund_upto\": 1705843623,\n \"cc_descriptor\": \"test-cardeye\",\n \"refund_availability\": \"NONE\",\n \"refundable_amount\": 9,\n \"success_redirect\": \"https://google.com\",\n \"failure_redirect\": \"https://yahoo.com\",\n \"cancel_redirect\": \"\",\n \"success_callback\": \"\",\n \"platform\": \"API\",\n \"created_from_ip\": \"149.86.53.48\",\n \"checkout_url\": \"http://18.214.100.20/payments/64bfdb7df63e36669499e82f/\",\n \"direct_post_url\": \"http://18.214.100.20/api/v1/p/64bfdb7df63e36669499e82f/\"\n}"}],"_postman_id":"992cca11-db04-4310-b1e2-253266f2d8cb"},{"name":"Refund","id":"e33a0639-6037-42bf-bc1c-b3f52eaaf14f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"url":"https://app.paybomb.tech/api/v1/purchases/657af976c3fceb7beb30eeb4/refund","description":"

This API is used to initate refund of the purchases that have status as PAID can be initiated for refund

Once the refund has been initiated, the status of the purchase would become REFUND_IN_PROCESS and once the refund has been approved by the bank, the status woud become REFUNDED

Purchase ID is mandatory for this API.

Currently we don't support partial refunds.

Response Examples

In the response examples you can see instances of both successful and unsuccessful in refund of purchases.

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"90ea93fb-a535-4243-bd42-deba195cc075","id":"90ea93fb-a535-4243-bd42-deba195cc075","name":"APIs","type":"folder"}},"urlObject":{"path":["purchases","657af976c3fceb7beb30eeb4","refund"],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"4dfa7e5a-5f94-414e-977f-9f55618c2b08","name":"Refund - Success","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"url":"https://app.paybomb.tech/api/v1/purchases/657af976c3fceb7beb30eeb4/refund"},"status":"Accepted","code":202,"_postman_previewlanguage":"json","header":[{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"1; mode=block"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"X-Frame-Options","value":"DENY"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Date","value":"Tue, 25 Jul 2023 16:33:43 GMT"},{"key":"Keep-Alive","value":"timeout=60"},{"key":"Connection","value":"keep-alive"}],"cookie":[],"responseTime":null,"body":"{\n \"purchaseId\": \"64bfdb7df63e36669499e82f\",\n \"client\": {\n \"bank_account\": \"\",\n \"bank_code\": \"\",\n \"email\": \"example@paybomb.tech\",\n \"phone\": \"\",\n \"full_name\": \"\",\n \"date_of_birth\": \"\",\n \"personal_code\": \"\",\n \"street_address\": \"test test\",\n \"country\": \"IN\",\n \"city\": \"123\",\n \"zip_code\": \"234567\",\n \"shipping_street_address\": \"\",\n \"shipping_country\": \"\",\n \"shipping_city\": \"\",\n \"shipping_zip_code\": \"\",\n \"cc\": [],\n \"bcc\": [],\n \"legal_name\": \"\",\n \"brand_name\": \"\",\n \"registration_number\": \"\",\n \"tax_number\": \"\",\n \"stateCode\": \"ca\"\n },\n \"updated_on\": 1690302819,\n \"type\": \"purchase\",\n \"force_recurring\": false,\n \"created_on\": 1690295168,\n \"purchase\": {\n \"currency\": \"USD\",\n \"products\": [\n {\n \"name\": \"dk\",\n \"quantity\": 1,\n \"price\": 9,\n \"discount\": 0,\n \"tax_percent\": \"0.00\"\n }\n ],\n \"total\": 9,\n \"language\": \"en\",\n \"notes\": \"\",\n \"debt\": 0,\n \"total_formatted\": 1,\n \"request_client_details\": [],\n \"timezone\": \"America/Edmonton\",\n \"email_message\": \"\"\n },\n \"payment\": {\n \"is_outgoing\": false,\n \"payment_type\": \"PURCHASE\",\n \"amount\": 9,\n \"currency\": \"USD\",\n \"net_amount\": 9,\n \"fee_amount\": 10.2591,\n \"pending_amount\": 0,\n \"pending_unfreeze_on\": null,\n \"description\": \"\",\n \"paid_on\": 1690295205,\n \"remote_paid_on\": 1690295205\n },\n \"issuer_details\": {\n \"website\": \"\",\n \"legal_street_address\": \"\",\n \"legal_country\": \"\",\n \"legal_city\": \"\",\n \"legal_zip_code\": \"\",\n \"bank_accounts\": [\n {\n \"bank_account\": \"\",\n \"bank_code\": \"\"\n }\n ],\n \"legal_name\": \"shoes\",\n \"brand_name\": \"shoes\",\n \"registration_number\": \"\",\n \"tax_number\": \"\"\n },\n \"transaction_data\": {\n \"payment_method\": \"\",\n \"flow\": \"payform\",\n \"extra\": {\n \"expiry_month\": \"10\",\n \"amount\": 9,\n \"card_issuer\": \"1-800-432-3117\",\n \"masked_pan\": \"411111XXXXXX1111\",\n \"card_brand\": \"VISA\",\n \"card_issuer_country\": \"US\",\n \"cardholder_name\": \"dk\",\n \"expiry_year\": \"23\"\n },\n \"country\": \"\",\n \"attempts\": [\n {\n \"client_ip\": \"149.86.53.48\",\n \"type\": \"execute\",\n \"payment_method\": \"VISA\",\n \"flow\": \"payform\",\n \"successful\": true,\n \"country\": \"US\",\n \"processing_time\": 1690295205,\n \"extra\": {\n \"expiry_month\": \"10\",\n \"amount\": 9,\n \"card_issuer\": \"1-800-432-3117\",\n \"masked_pan\": \"411111XXXXXX1111\",\n \"card_brand\": \"VISA\",\n \"card_issuer_country\": \"US\",\n \"cardholder_name\": \"dk\",\n \"expiry_year\": \"23\"\n }\n },\n {\n \"client_ip\": \"149.86.53.48\",\n \"type\": \"refund\",\n \"successful\": true,\n \"processing_time\": 1690302819,\n \"extra\": {\n \"amount\": 9\n }\n }\n ]\n },\n \"status\": \"REFUNDED\",\n \"status_history\": [\n {\n \"status\": \"created\",\n \"timestamp\": 1765294731\n },\n {\n \"status\": \"pending_execute\",\n \"timestamp\": 1765294744\n },\n {\n \"status\": \"payment_in_process\",\n \"timestamp\": 1765294754\n },\n {\n \"status\": \"paid\",\n \"timestamp\": 1765297331\n },\n {\n \"status\": \"refunded\",\n \"timestamp\": 1765624009\n }\n ],\n \"viewedOn\": 1690299929,\n \"is_test\": false,\n \"brand_id\": \"bd69e8a5-adcf-40de-9e43-2b87cb129a5e\",\n \"send_receipt\": false,\n \"is_recurring_token\": false,\n \"skip_capture\": false,\n \"reference_generated\": \"PS192\",\n \"issued\": \"2023-07-25\",\n \"due\": 1690295168,\n \"refund_upto\": 1705843623,\n \"cc_descriptor\": \"test-cardeye\",\n \"refund_availability\": \"NONE\",\n \"refundable_amount\": 0,\n \"success_redirect\": \"https://google.com\",\n \"failure_redirect\": \"https://yahoo.com\",\n \"cancel_redirect\": \"\",\n \"success_callback\": \"\",\n \"platform\": \"API\",\n \"created_from_ip\": \"149.86.53.48\",\n \"checkout_url\": \"http://18.214.100.20/payments/64bfdb7df63e36669499e82f/\",\n \"direct_post_url\": \"http://18.214.100.20/api/v1/p/64bfdb7df63e36669499e82f/\"\n}"},{"id":"cf7ee07e-1079-4869-919c-a7cc2fab47cd","name":"Refund - Pending","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"url":"https://app.paybomb.tech/api/v1/purchases/657af976c3fceb7beb30eeb4/refund"},"status":"Accepted","code":202,"_postman_previewlanguage":"json","header":[{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"1; mode=block"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"X-Frame-Options","value":"DENY"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Date","value":"Tue, 25 Jul 2023 16:33:43 GMT"},{"key":"Keep-Alive","value":"timeout=60"},{"key":"Connection","value":"keep-alive"}],"cookie":[],"responseTime":null,"body":"{\n \"purchaseId\": \"64bfdb7df63e36669499e82f\",\n \"client\": {\n \"bank_account\": \"\",\n \"bank_code\": \"\",\n \"email\": \"example@paybomb.tech\",\n \"phone\": \"\",\n \"full_name\": \"\",\n \"date_of_birth\": \"\",\n \"personal_code\": \"\",\n \"street_address\": \"test test\",\n \"country\": \"IN\",\n \"city\": \"123\",\n \"zip_code\": \"234567\",\n \"shipping_street_address\": \"\",\n \"shipping_country\": \"\",\n \"shipping_city\": \"\",\n \"shipping_zip_code\": \"\",\n \"cc\": [],\n \"bcc\": [],\n \"legal_name\": \"\",\n \"brand_name\": \"\",\n \"registration_number\": \"\",\n \"tax_number\": \"\",\n \"stateCode\": \"ca\"\n },\n \"updated_on\": 1690302819,\n \"type\": \"purchase\",\n \"force_recurring\": false,\n \"created_on\": 1690295168,\n \"purchase\": {\n \"currency\": \"USD\",\n \"products\": [\n {\n \"name\": \"dk\",\n \"quantity\": 1,\n \"price\": 9,\n \"discount\": 0,\n \"tax_percent\": \"0.00\"\n }\n ],\n \"total\": 9,\n \"language\": \"en\",\n \"notes\": \"\",\n \"debt\": 0,\n \"total_formatted\": 1,\n \"request_client_details\": [],\n \"timezone\": \"America/Edmonton\",\n \"email_message\": \"\"\n },\n \"payment\": {\n \"is_outgoing\": false,\n \"payment_type\": \"PURCHASE\",\n \"amount\": 9,\n \"currency\": \"USD\",\n \"net_amount\": 9,\n \"fee_amount\": 10.2591,\n \"pending_amount\": 0,\n \"pending_unfreeze_on\": null,\n \"description\": \"\",\n \"paid_on\": 1690295205,\n \"remote_paid_on\": 1690295205\n },\n \"issuer_details\": {\n \"website\": \"\",\n \"legal_street_address\": \"\",\n \"legal_country\": \"\",\n \"legal_city\": \"\",\n \"legal_zip_code\": \"\",\n \"bank_accounts\": [\n {\n \"bank_account\": \"\",\n \"bank_code\": \"\"\n }\n ],\n \"legal_name\": \"shoes\",\n \"brand_name\": \"shoes\",\n \"registration_number\": \"\",\n \"tax_number\": \"\"\n },\n \"transaction_data\": {\n \"payment_method\": \"\",\n \"flow\": \"payform\",\n \"extra\": {\n \"expiry_month\": \"10\",\n \"amount\": 9,\n \"card_issuer\": \"1-800-432-3117\",\n \"masked_pan\": \"411111XXXXXX1111\",\n \"card_brand\": \"VISA\",\n \"card_issuer_country\": \"US\",\n \"cardholder_name\": \"dk\",\n \"expiry_year\": \"23\"\n },\n \"country\": \"\",\n \"attempts\": [\n {\n \"client_ip\": \"149.86.53.48\",\n \"type\": \"execute\",\n \"payment_method\": \"VISA\",\n \"flow\": \"payform\",\n \"successful\": true,\n \"country\": \"US\",\n \"processing_time\": 1690295205,\n \"extra\": {\n \"expiry_month\": \"10\",\n \"amount\": 9,\n \"card_issuer\": \"1-800-432-3117\",\n \"masked_pan\": \"411111XXXXXX1111\",\n \"card_brand\": \"VISA\",\n \"card_issuer_country\": \"US\",\n \"cardholder_name\": \"dk\",\n \"expiry_year\": \"23\"\n }\n },\n {\n \"client_ip\": \"149.86.53.48\",\n \"type\": \"refund\",\n \"successful\": true,\n \"processing_time\": 1690302819,\n \"extra\": {\n \"amount\": 9\n }\n }\n ]\n },\n \"status\": \"REFUND_IN_PROCESS\",\n \"status_history\": [\n {\n \"status\": \"created\",\n \"timestamp\": 1690295168\n },\n {\n \"status\": \"pending_execute\",\n \"timestamp\": 1690295193\n },\n {\n \"status\": \"payment_in_process\",\n \"timestamp\": 1690295205\n },\n {\n \"status\": \"paid\",\n \"timestamp\": 1690296521\n },\n {\n \"status\": \"viewed\",\n \"timestamp\": 1690299929\n },\n {\n \"status\": \"refund_in_process\",\n \"timestamp\": 1690302819\n }\n ],\n \"viewedOn\": 1690299929,\n \"is_test\": false,\n \"brand_id\": \"bd69e8a5-adcf-40de-9e43-2b87cb129a5e\",\n \"send_receipt\": false,\n \"is_recurring_token\": false,\n \"skip_capture\": false,\n \"reference_generated\": \"PS192\",\n \"issued\": \"2023-07-25\",\n \"due\": 1690295168,\n \"refund_upto\": 1705843623,\n \"cc_descriptor\": \"test-cardeye\",\n \"refund_availability\": \"NONE\",\n \"refundable_amount\": 0,\n \"success_redirect\": \"https://google.com\",\n \"failure_redirect\": \"https://yahoo.com\",\n \"cancel_redirect\": \"\",\n \"success_callback\": \"\",\n \"platform\": \"API\",\n \"created_from_ip\": \"149.86.53.48\",\n \"checkout_url\": \"http://18.214.100.20/payments/64bfdb7df63e36669499e82f/\",\n \"direct_post_url\": \"http://18.214.100.20/api/v1/p/64bfdb7df63e36669499e82f/\"\n}"},{"id":"7852feae-cff6-46a3-8072-79fa0f2c7caf","name":"Refund - Error","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"url":"https://app.paybomb.tech/api/v1/purchases/657af976c3fceb7beb30eeb4/refund"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"1; mode=block"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"X-Frame-Options","value":"DENY"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Date","value":"Thu, 13 Jul 2023 17:49:58 GMT"},{"key":"Connection","value":"close"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"Only Purchases with `status == (paid)` can be refunded.\",\n \"code\": \"transaction_error\"\n}"}],"_postman_id":"e33a0639-6037-42bf-bc1c-b3f52eaaf14f"},{"name":"Payment Methods","id":"e5fa5b65-1938-4ecc-8453-8b91585d361e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"url":"https://app.paybomb.tech/api/v1/payment_methods?brand_id=aff0471b-e37d-4e76-9dee-d235063bf276","description":"

This API gives back the list of Payment methods available for a brand.

Cancels an in-progress or completed purchase transaction, preventing further processing or reversing the authorization hold. Use this endpoint to void a transaction that has not yet been settled to the merchant's account.

When to use:

Post-creation cancellation: Cancel a purchase immediately after it has been created via the Purchase API, before the customer completes the payment flow.
\n
Pre-redirect cancellation: Cancel a transaction after completing the server-to-server (S2S) call but before redirecting the cardholder to the callbackURL. This is useful when your backend validation logic determines the transaction should not proceed (e.g., inventory check failure, fraud flag, duplicate order detection).
\n

Purchase ID is mandatory for this API.

Overview

Paybomb supports the concept of whitelisted cards. The merchant can send Paybomb a list of cards that are to be whitelisted. Once whitelisted, only whitelisted cards are allowed to be transacted for that merchant.

The merchant can check the individual card status with this API by giving the email and card numbers of the customers.

Mandatory Parameters (in body)

\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameters
email
card_num

Other parameters:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameters
signup_date
deposit_date
number_of_deposits

Response Examples

In the response examples, you can observe both instances of verifying whether a card exists in a merchant's whitelist, one for an existing card and another for a non-existing card.

Overview

The merchant can upload a list of whitelist cards and email ids through this API. All cards successfully uploaded will be considered whitelisted and allowed for that merchant.

Mandatory parameters in the request body:

\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Notes
csvFile	Upload a CSV file

Please note:

CSV file should contain the following headers (both mandatory)
\n
1. card_number
  \n
2. email_id
  \n
\n
CSV file should not be empty
\n

public class FileUploader {\n    public static void uploadFile(String apiUrl, String filePath, String authorizationHeader) {\n        try {\n            File file = new File(filePath);\n            OkHttpClient client = new OkHttpClient();\n            RequestBody requestBody = new MultipartBody.Builder().setType(MultipartBody.FORM)\n                    .addFormDataPart(\"csvFile\", file.getName(), RequestBody.create(MediaType.parse(\"text/csv\"), file))\n                    .build();\n            Request request = new Request.Builder().url(apiUrl).post(requestBody)\n                    .addHeader(\"Authorization\", authorizationHeader).build();\n            Response response = client.newCall(request).execute();\n            if (response.code() == 202) {\n                System.out.println(\"File uploaded successfully!\");\n                System.out.println(\"Response: \" + response.body().string());\n            } else {\n                System.out.println(\"File upload failed.\");\n                System.out.println(\"Status: \" + response.code());\n                System.out.println(\"Error: \" + response.body().string());\n            }\n        } catch (IOException e) {\n            e.printStackTrace();\n        }\n    }\n    public static void main(String[] args) {\n        String apiUrl = \"https://{{base_url}}/api/v1/whitelist/upload\";\n        String filePath = \"whitelist.csv.file.path\";\n        String authorizationHeader = \"Bearer YOUR API KEY\";\n        uploadFile(apiUrl, filePath, authorizationHeader);\n    }\n}\n\n

\n","urlObject":{"protocol":"https","path":["api","v1","whitelist","upload",""],"host":["api","paybomb","net"],"query":[],"variable":[]}},"response":[{"id":"e593b6ac-e85a-4172-a7ce-bf54de4d9217","name":"Whitelist Upload success","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"multipart/form-data; boundary=","disabled":true}],"body":{"mode":"formdata","formdata":[{"key":"csvFile","type":"file","fileNotInWorkingDirectoryWarning":"This file isn't in your working directory. Teammates you share this request with won't be able to use this file. To make collaboration easier you can setup your working directory in Settings.","filesNotInWorkingDirectory":["/C:/Users/HP/Desktop/Important/upladingfile/merchantwhitlist.csv"],"src":[]}]},"url":"https://api.paybomb.net/api/v1/whitelist/upload/"},"status":"Accepted","code":202,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Fri, 14 Jun 2024 09:10:47 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"1; mode=block"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"Strict-Transport-Security","value":"max-age=31536000 ; includeSubDomains"},{"key":"X-Frame-Options","value":"SAMEORIGIN"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"CF-Cache-Status","value":"DYNAMIC"},{"key":"Report-To","value":"{\"endpoints\":[{\"url\":\"https:\\/\\/a.nel.cloudflare.com\\/report\\/v4?s=bIgUFhs3TU2505qZe4IpSLiaJtI2gsplNDvsVWdKl76AWQdcisezEHOW6t%2BxTCj%2Bxs%2B23gnSeMCWrqwG0CYQONFHXhXb9ZHNtIYMuHWzvjLhVEChIX%2BYpODoLqzs9OP4r5q%2F9ABSXBs%3D\"}],\"group\":\"cf-nel\",\"max_age\":604800}"},{"key":"NEL","value":"{\"success_fraction\":0,\"report_to\":\"cf-nel\",\"max_age\":604800}"},{"key":"Server","value":"cloudflare"},{"key":"CF-RAY","value":"893930730b8b0c3f-MRS"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"totalRecords\": 3,\n \"totalApproved\": 3,\n \"status\": \"success\"\n}"},{"id":"00e42eaa-365d-4cad-98aa-00aef5eb789c","name":"Whitelist Upload failure","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"multipart/form-data; boundary=","disabled":true}],"body":{"mode":"formdata","formdata":[{"key":"csvFile","type":"file","fileNotInWorkingDirectoryWarning":"This file isn't in your working directory. Teammates you share this request with won't be able to use this file. To make collaboration easier you can setup your working directory in Settings.","filesNotInWorkingDirectory":["/C:/Users/HP/Desktop/Important/upladingfile/merchantwhitlist.csv"],"src":[]}]},"url":"https://api.paybomb.net/api/v1/whitelist/upload/"},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Fri, 14 Jun 2024 09:11:50 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"1; mode=block"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"Strict-Transport-Security","value":"max-age=31536000 ; includeSubDomains"},{"key":"X-Frame-Options","value":"SAMEORIGIN"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"CF-Cache-Status","value":"DYNAMIC"},{"key":"Report-To","value":"{\"endpoints\":[{\"url\":\"https:\\/\\/a.nel.cloudflare.com\\/report\\/v4?s=9tel4sXa6ymyhRDTyNC%2B%2Bg2Msz1MivhgHbawlLF7JvTAgfonvRaas8MQeMtVVK95cziZLoZUKaThXJOAAeZW6iZ6fqlK5flpZjGxKwInEyKzZJr9JLDSQbNt5Um%2BK4zdbMZfkHV2seg%3D\"}],\"group\":\"cf-nel\",\"max_age\":604800}"},{"key":"NEL","value":"{\"success_fraction\":0,\"report_to\":\"cf-nel\",\"max_age\":604800}"},{"key":"Server","value":"cloudflare"},{"key":"CF-RAY","value":"893931f998280c3f-MRS"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"Authorization header missing\",\n \"code\": \"authentication_failed\",\n \"status\": \"fail\"\n}"}],"_postman_id":"9a451d05-18fa-4f86-a1f0-743133f3a8ad"},{"name":"PayOut","id":"26518286-bbc7-4c36-9e9c-d584039d3994","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"body":{"mode":"raw","raw":"{\n \"client\": {\n \"email\": \"rahul@gmail.com\",\n \"country\": \"GB\",\n \"city\": \"London\",\n \"stateCode\": \"QLD\",\n \"full_name\": \"Rahul Jain\",\n \"street_address\": \"10 New Burlington Street Apt. 214\",\n \"zip_code\": \"W1S 3BE\",\n \"phone\": \"+44 9876543210\",\n \"gender\": \"M\",\n \"date_of_birth\": \"1970-07-10\"\n },\n \"purpose\": \"Testing cards payout\",\n \"currency\": \"GBP\",\n \"merchantRef\": \"YOUR ORDER ID\", // optional\n \"payoutMethod\": \"PAYOUT-CARDS\",\n \"amount\": 100.0,\n \"success_redirect\": \"https://your.success.redirect.com\",\n \"pending_redirect\": \"https://your.pending.redirect.com\",\n \"failure_redirect\": \"https://your.failure.redirect.com\",\n \"success_callback\": \"https://your.success.callback.com\",\n \"failure_callback\": \"https://your.failure.callback.com\",\n \"extraParam\": {\n \"cardNumber\": \"5431240006334004\",\n \"cardHolderName\": \"Rahul Agarwal\",\n \"expiryYear\": \"2030\",\n \"expiryMonth\": \"11\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/payout/","description":"

Overview

The Original Credit Transaction (OCT), commonly referred to as Push to Card, enables merchants to facilitate near-instantaneous fund transfers directly to a customer’s eligible Visa or Mastercard debit or credit card. Unlike traditional refund processes that can only return funds from a previous purchase, OCT allows for independent disbursements of funds to a cardholder's account.

This feature is designed for high-velocity industries that require frictionless, real-time payouts, such as:

Gaming & Betting: Real-time withdrawal of player winnings.
\n
Marketplaces: Payouts to sellers or service providers.
\n
Corporate Disbursements: Instant insurance claims, rebates, or compensation payments.
\n
Merchant Settlements: Faster access to processed funds for sub-merchants.
\n

By utilizing the Paybomb /payout API with the PAYOUT-CARDS method, you benefit from a unified orchestration layer that handles the complexities of card network routing, ensuring high success rates and global reach while maintaining the same security standards as your standard payment integrations.

Integration Steps

Enable OCT: Ensure \"Push to Card\" permissions are enabled for your merchant account in the Paybomb Merchant Portal.
\n
Collect Card Details: Use a secure method to collect the recipient's card number and expiry date or can you Paybomb's cashier to do that.
\n
Execute Payout: Call the /payout endpoint with the OCT-specific payout method.
\n
Handle Webhooks: Listen for the paid or failure events to update your internal records.
\n

Mandatory parameters in the request body:

Parameter	Required	Notes
client.email	Yes	The customer's email.
client.phone	Yes	The customer's phone number along with the country code. Example: +91 9634088651
client.city	Yes	The customer's city.
client.country	Yes	ISO-3166 Country Code. Must be upper case. Example “SG” (Alpha2)
client.stateCode	Optional	Example “AL”, “XZ”. Must be in upper case.
Client.street_address	Optional	The customer's address.
client.zip_code	Optional	The customer's ZIP or postal code. If country=US, zip format must be NNNNN or NNNNN-NNNN.
currency	Yes	ISO 4217 code for currency you want to send the transaction in. Please note, the currency has to be enabled by the account manager for your account.
amount	Yes	amount in decimal format. example 1: EUR 5 , should be sent as 5.00 example 2: USD 10 and 37 cents , should be sent as 10.37
payoutMethod	Optional	example: PAYOUT-CARDS
success_redirect	Yes	URL to send the user if the transactions is successful.
pending_redirect	Yes	URL to send the user if the transactions is in pending.
failure_redirect	Yes	URL to send the user if the transactions is unsuccessful.
Purpose	Optional	The purpose of doing a payout.
extraParam.cardNumber	Yes	The recipient's 16-digit card number.
extraParam.expiryYear	Yes	YYYY format (e.g., 2028).
extraParam.expiryMonth	Yes	MM format (e.g., 05).
extraParam.cardHolderName	Yes	The receiver's Full Name. Preferred a 2 word name with each word atleast 3 characters long.

Note:

If the merchant is not PCI DSS compliant then they will need to use our cashier and asking the user to enter the card details there. Check the cashier section for more details. If the merchant is PCI DSS compliant then they can use the payout API and send the card details as shown above.

If the merchant wants to use token_reference for doing a payout, then please have a look at the Network Tokenisation Section.

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"90ea93fb-a535-4243-bd42-deba195cc075","id":"90ea93fb-a535-4243-bd42-deba195cc075","name":"APIs","type":"folder"}},"urlObject":{"path":["payout",""],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"98bda83b-fcda-4c9b-b970-b62768757137","name":"Success","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"email\": \"rahul@gmail.com\",\r\n \"country\": \"GB\",\r\n \"city\": \"London\",\r\n \"stateCode\": \"QLD\",\r\n \"full_name\": \"Rahul Jain\",\r\n \"street_address\": \"10 New Burlington Street Apt. 214\",\r\n \"zip_code\": \"W1S 3BE\",\r\n \"phone\": \"+44 9876543210\",\r\n \"gender\": \"M\",\r\n \"date_of_birth\": \"1970-07-10\"\r\n },\r\n \"purpose\": \"Testing cards payout\",\r\n \"currency\": \"GBP\",\r\n \"merchantRef\": \"YOUR ORDER ID\", // optional\r\n \"payoutMethod\": \"PAYOUT-CARDS\",\r\n \"amount\": 100.0,\r\n \"success_redirect\": \"https://your.success.redirect.com\",\r\n \"pending_redirect\": \"https://your.pending.redirect.com\",\r\n \"failure_redirect\": \"https://your.failure.redirect.com\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\",\r\n \"extraParam\": {\r\n \"cardNumber\": \"5431240006334004\",\r\n \"cardHolderName\": \"Rahul Agarwal\",\r\n \"expiryYear\": \"2030\",\r\n \"expiryMonth\": \"11\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/payout/"},"status":"Accepted","code":202,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"payoutId\": \"6977137755e0628e3600c562\",\r\n \"client\": {\r\n \"email\": \"rahul@gmail.com\",\r\n \"country\": \"GB\",\r\n \"city\": \"London\",\r\n \"stateCode\": \"QLD\",\r\n \"full_name\": \"Rahul Jain\",\r\n \"street_address\": \"10 New Burlington Street Apt. 214\",\r\n \"zip_code\": \"W1S 3BE\",\r\n \"phone\": \"+44 9876543210\",\r\n \"gender\": \"M\",\r\n \"date_of_birth\": \"1970-07-10\"\r\n },\r\n \"updated_on\": 1769411447,\r\n \"extraParam\": {\r\n \"cardNumber\": \"5431240006334004\",\r\n \"cardHolderName\": \"Rahul Agarwal\",\r\n \"expiryYear\": \"2030\",\r\n \"expiryMonth\": \"11\"\r\n },\r\n \"payoutMethod\": \"PAYOUT-CARDS\",\r\n \"amountUnit\": \"MAJOR\",\r\n \"amount\": 100.0,\r\n \"errorMsg\": \"\",\r\n \"purpose\": \"Testing cards payout\",\r\n \"created_on\": 1769411447,\r\n \"merchantRef\": \"YOUR ORDER ID\",\r\n \"status\": \"PAID\",\r\n \"status_history\": [\r\n {\r\n \"status\": \"created\",\r\n \"timestamp\": 1769411447\r\n },\r\n {\r\n \"status\": \"payout_in_process\",\r\n \"timestamp\": 1769411447\r\n },\r\n {\r\n \"status\": \"paid\",\r\n \"timestamp\": 1769411447\r\n },\r\n\r\n ],\r\n \"currency\": \"GBP\",\r\n \"extraFee\": \"0\",\r\n \"paymentOn\": 0,\r\n \"checkout_url\": \"https://test4.paymentsclub.net/payout/092e59f94279a3742fa3715fe9a2112a/\",\r\n \"taxAmount\": 0.0,\r\n \"taxPercent\": 0.0,\r\n \"success_redirect\": \"https://your.success.redirect.com\",\r\n \"pending_redirect\": \"https://your.pending.redirect.com\",\r\n \"failure_redirect\": \"https://your.failure.redirect.com\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\"\r\n \"redirectType\": \"POST\",\r\n \"sessionId\": \"\",\r\n \"surcharge\": 0.0,\r\n \"surchargeType\": \"\",\r\n \"trxMethod\": \"CARDS\",\r\n \"success_callback\": \"\",\r\n \"failure_callback\": \"\"\r\n}"},{"id":"24b2f78b-5208-423a-a643-0ef19be61054","name":"Error","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"email\": \"rahul@gmail.com\",\r\n \"country\": \"GB\",\r\n \"city\": \"London\",\r\n \"stateCode\": \"QLD\",\r\n \"full_name\": \"Rahul Jain\",\r\n \"street_address\": \"10 New Burlington Street Apt. 214\",\r\n \"zip_code\": \"W1S 3BE\",\r\n \"phone\": \"+44 9876543210\",\r\n \"gender\": \"M\",\r\n \"date_of_birth\": \"1970-07-10\"\r\n },\r\n \"purpose\": \"Testing cards payout\",\r\n \"currency\": \"GBP\",\r\n \"merchantRef\": \"YOUR ORDER ID\", // optional\r\n \"payoutMethod\": \"PAYOUT-CARDS\",\r\n \"amount\": 100.0,\r\n \"success_redirect\": \"https://your.success.redirect.com\",\r\n \"pending_redirect\": \"https://your.pending.redirect.com\",\r\n \"failure_redirect\": \"https://your.failure.redirect.com\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\",\r\n \"extraParam\": {\r\n \"cardNumber\": \"5431240006334004\",\r\n \"cardHolderName\": \"Rahul Agarwal\",\r\n \"expiryYear\": \"2030\",\r\n \"expiryMonth\": \"11\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/payout/"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"payoutId\": \"6977137755e0628e3600c562\",\r\n \"client\": {\r\n \"email\": \"rahul@gmail.com\",\r\n \"country\": \"GB\",\r\n \"city\": \"London\",\r\n \"stateCode\": \"QLD\",\r\n \"full_name\": \"Rahul Jain\",\r\n \"street_address\": \"10 New Burlington Street Apt. 214\",\r\n \"zip_code\": \"W1S 3BE\",\r\n \"phone\": \"+44 9876543210\",\r\n \"gender\": \"M\",\r\n \"date_of_birth\": \"1970-07-10\"\r\n },\r\n \"updated_on\": 1769411447,\r\n \"extraParam\": {\r\n \"cardNumber\": \"5431240006334004\",\r\n \"cardHolderName\": \"Rahul Agarwal\",\r\n \"expiryYear\": \"2030\",\r\n \"expiryMonth\": \"11\"\r\n },\r\n \"payoutMethod\": \"PAYOUT-CARDS\",\r\n \"amountUnit\": \"MAJOR\",\r\n \"amount\": 100.0,\r\n \"errorMsg\": \"\",\r\n \"purpose\": \"Testing cards payout\",\r\n \"created_on\": 1769411447,\r\n \"merchantRef\": \"YOUR ORDER ID\",\r\n \"status\": \"error\",\r\n \"status_history\": [\r\n {\r\n \"status\": \"created\",\r\n \"timestamp\": 1769411447\r\n },\r\n {\r\n \"status\": \"error\",\r\n \"timestamp\": 1769411447\r\n },\r\n\r\n ],\r\n \"currency\": \"GBP\",\r\n \"extraFee\": \"0\",\r\n \"paymentOn\": 0,\r\n \"checkout_url\": \"https://test4.paymentsclub.net/payout/092e59f94279a3742fa3715fe9a2112a/\",\r\n \"taxAmount\": 0.0,\r\n \"taxPercent\": 0.0,\r\n \"success_redirect\": \"https://your.success.redirect.com\",\r\n \"pending_redirect\": \"https://your.pending.redirect.com\",\r\n \"failure_redirect\": \"https://your.failure.redirect.com\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\"\r\n \"redirectType\": \"POST\",\r\n \"sessionId\": \"\",\r\n \"surcharge\": 0.0,\r\n \"surchargeType\": \"\",\r\n \"trxMethod\": \"BANKTRANSFER\",\r\n \"success_callback\": \"\",\r\n \"failure_callback\": \"\"\r\n}"}],"_postman_id":"26518286-bbc7-4c36-9e9c-d584039d3994"}],"id":"90ea93fb-a535-4243-bd42-deba195cc075","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"221f3b39-56b1-4f1c-810e-f6d5cb26aaf9"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"b7cbefe1-d1ca-4c8e-9d59-8c9425672933"}}],"_postman_id":"90ea93fb-a535-4243-bd42-deba195cc075","description":""}],"id":"b1d59495-e887-499f-96b9-1358c52e79c9","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"ca558a24-913f-40df-a0ca-05290c210518"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"b479be32-7aba-4e69-a88d-f3605660de22"}}],"_postman_id":"b1d59495-e887-499f-96b9-1358c52e79c9","description":""},{"name":"💰 APMs (Alternative Payment Methods)","item":[{"name":"🌎 Google Pay Redirect","item":[{"name":"Concepts","item":[],"id":"33d9cd54-f387-4c78-8d28-7be6bc7c41ba","description":"

Overview

Google Pay enables customers to make payments on a merchant’s website or app using credit or debit cards securely stored in their Google Account. During checkout, Google Pay presents a payment sheet where customers can select their preferred card and confirm the transaction.

Customers add their payment cards to the Google Pay wallet, which securely stores the card details. When making a purchase, they simply choose Google Pay as the payment method and complete the payment using a saved card—eliminating the need to enter card information repeatedly.

Features

Convenient: Customers can pay using cards already saved in Google Pay, reducing friction during checkout.
\n
Secure: Uses tokenization to ensure sensitive card information is never exposed during the payment flow.
\n
3D Secure support: The payment handle created through the integration supports 3D Secure authentication when required, enabling secure transactions.
\n
Wide coverage: Supported across multiple regions and currencies.
\n

By integrating Google Pay through the Paybomb API, you can offer your customers a fast, secure, and seamless payment experience.

Note

This is a redirection-based payment method. During the payment flow, the user is redirected to a third-party application or interface, where the Google Pay button is displayed for completing the transaction.

\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"76da24b6-23ae-42b8-bfc0-d0fb21a4346e"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"c8161120-823e-4964-9c32-42693beea2ef"}}],"_postman_id":"33d9cd54-f387-4c78-8d28-7be6bc7c41ba"},{"name":"APIs","item":[{"name":"Purchases","id":"2b3ad128-9889-4cd0-a2e2-129edc8ab63f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer Token"}],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"email\": \"rahultest@gmail.com\",\r\n \"country\": \"GB\",\r\n \"city\": \"London\",\r\n \"stateCode\": \"RJ\",\r\n \"street_address\": \"10 New Burlington StreetApt. 214\",\r\n \"zip_code\": \"W1S 3BE\",\r\n \"date_of_birth\": \"1994-31-04\",\r\n \"phone\": \"+91 9634088561\",\r\n \"full_name\": \"Rahul Agarwal\"\r\n },\r\n \"purchase\": {\r\n \"currency\": \"EUR\",\r\n \"products\": [\r\n {\r\n \"name\": \"gaming cards \",\r\n \"price\": 10\r\n }\r\n ]\r\n },\r\n \"brand_id\": \"your-brandid\",\r\n \"paymentMethod\": \"GOOGLEPAY-REDIRECT\",\r\n \"success_redirect\": \"https://your-redirect-url?issucces=true\",\r\n \"pending_redirect\": \"https://your-redirect-url?ispending=true\",\r\n \"failure_redirect\": \"https://your-redirect-url?isfailure=true\",\r\n \"success_callback\": \"https://your-webhook-url\",\r\n \"failure_callback\": \"https://your-webhook-url\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/purchases/","description":"

To Initiate a payment, the very first call to make is /purchases with the required data in the request body.

To generate a Purchase, you are required to provide the Brand ID (in the request body) and API key (in the header) Both can be located in the Dashboard section of your merchant account login.

The request body structure is shown on the request body of the example request shown here.

The following (see table below) are the mandatory parameters that are required to create a purchase request.

Parameters in the request body:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Notes
client.full_name	Conditional. But Recommended to pass the complete name of the client. Atleast 2 words recommended.
client.email	Conditional. But Recommended to pass a correct email id.
paymentMethod	Conditional. Mandatory if you are not using Paybomb Cashier. Else Non Mandatory. Value: GOOGLEPAY-REDIRECT
purchase.currency	Mandatory. ISO 4217 code for currency you want to send the transaction in. This should be 'BRL' for PIX.
purchase.products.name	Mandatory.
purchase.products.price	Mandatory. Price in decimal format upto 2 decimals. example 1: EUR 5 , should be sent as 5.00 example 2: USD 10 and 37 cents , should be sent as 10.37
brand_id	Mandatory. Obtain from Dashboard section of your merchant account login.
success_redirect	Mandatory. URL to send the user if the transactions is successful.
pending_redirect	Mandatory. URL to send the user if the transactions is in progress state.
failure_redirect	Mandatory URL to send the user if the transactions has failed.

Optional Parameters

expireInMin

This parameter, when passed in the PayIn request, sets the time window within which a customer should make the Interac payment through their bank's app. If a customer doesn't complete the payment within the configured time window, the status of the payment will be marked as 'EXPIRED' in Paybomb.

However, in certain cases, a payment made outside of this window could still be successful i.e. customer's account may be debited which would result in inconsistencies among Paybomb's, merchant's and customer's status of the transaction. To avoid such cases it is advised to set the expiry time limit appropriately and advise the customers to make payment within this window. However, if there is an inconsistency between the status at Paybomb and at customer's Bank, the merchant and Paybomb will reconcile the amounts during the settlement.

merchantRef

The merchantRef parameter, although not mandatory, is strongly advised for merchants to specify. Its inclusion offers two significant advantages for the merchant:

Prevention of Duplicate Requests: When a merchantRef is utilized, it acts as a unique identifier. This means that if a second purchase request is made using the same merchantRef (reference number), the system will recognize it and prevent duplicate transactions from occurring. This prevents unintended or duplicate purchases.
\n
Facilitation of Transaction Retrieval: In situations where the response from the initial purchase request times out or the 'purchaseId' isn't received, having the merchantRef allows the merchant to retrieve detailed transaction information. This ensures they can track and access the specific purchase details related to that reference, even if the immediate response was not received.
\n

However, if the merchant does not specify the 'merchantRef' parameter, the platform will automatically assign and use an internal 'purchaseId' as a reference for that transaction.

paymentMethod

The paymentMethod parameter identifies which payment solution merchant wants to use to perform a transaction. If parameter is provided, then Paybomb will perform direct payment with the selected payment method instead of loading Paybomb URL.

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"7e4346a7-1c22-4378-bb36-3f70a3998bbd","id":"7e4346a7-1c22-4378-bb36-3f70a3998bbd","name":"APIs","type":"folder"}},"urlObject":{"path":["purchases",""],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"4567ae3a-99b1-4064-8507-b64301d3de1a","name":"Purchase - success","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer Token"}],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"email\": \"rahultest@gmail.com\",\r\n \"country\": \"GB\",\r\n \"city\": \"London\",\r\n \"stateCode\": \"RJ\",\r\n \"street_address\": \"10 New Burlington StreetApt. 214\",\r\n \"zip_code\": \"W1S 3BE\",\r\n \"date_of_birth\": \"1994-31-04\",\r\n \"phone\": \"+91 9634088561\",\r\n \"full_name\": \"Rahul Agarwal\"\r\n },\r\n \"purchase\": {\r\n \"currency\": \"EUR\",\r\n \"products\": [\r\n {\r\n \"name\": \"gaming cards \",\r\n \"price\": 10\r\n }\r\n ]\r\n },\r\n \"brand_id\": \"your-brandid\",\r\n \"paymentMethod\": \"GOOGLEPAY-REDIRECT\",\r\n \"success_redirect\": \"https://your-redirect-url?issucces=true\",\r\n \"pending_redirect\": \"https://your-redirect-url?ispending=true\",\r\n \"failure_redirect\": \"https://your-redirect-url?isfailure=true\",\r\n \"success_callback\": \"https://your-webhook-url\",\r\n \"failure_callback\": \"https://your-webhook-url\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/purchases"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"purchaseId\": \"69634df44549cbd3547ac750\",\r\n \"client\": {\r\n \"customerId\": \"NA\",\r\n \"email\": \"rahultest@gmail.com\",\r\n \"phone\": \"+91 9634088561\",\r\n \"full_name\": \"Rahul Agarwal\",\r\n \"date_of_birth\": \"1994-31-04\",\r\n \"street_address\": \"10 New Burlington StreetApt. 214\",\r\n \"country\": \"GB\",\r\n \"city\": \"London\",\r\n \"zip_code\": \"W1S 3BE\",\r\n \"cc\": [],\r\n \"bcc\": [],\r\n \"stateCode\": \"RJ\"\r\n },\r\n \"updated_on\": 1768115701,\r\n \"type\": \"purchase\",\r\n \"paymentMethod\": \"GOOGLEPAY-REDIRECT\",\r\n \"amountUnit\": \"MAJOR\",\r\n \"errorMsg\": \"\",\r\n \"errorCode\": \"NA\",\r\n \"force_recurring\": false,\r\n \"created_on\": 1768115700,\r\n \"merchantRef\": \"69634df44549cbd3547ac750\",\r\n \"purchase\": {\r\n \"currency\": \"EUR\",\r\n \"products\": [\r\n {\r\n \"name\": \"gaming cards\",\r\n \"quantity\": 1.0,\r\n \"price\": 1.0,\r\n \"discount\": 0,\r\n \"tax_percent\": \"0.00\"\r\n }\r\n ],\r\n \"total\": 1.0,\r\n \"requestAmount\": 1.0,\r\n \"language\": \"en\",\r\n \"notes\": \"\",\r\n \"debt\": 0,\r\n \"total_formatted\": 1.0,\r\n \"taxAmount\": 0.0,\r\n \"taxPercent\": 0.0,\r\n \"request_client_details\": [],\r\n \"email_message\": \"\"\r\n },\r\n \"payment\": {\r\n \"is_outgoing\": false,\r\n \"payment_type\": \"PURCHASE\",\r\n \"amount\": 1.0,\r\n \"currency\": \"EUR\",\r\n \"net_amount\": 1.0,\r\n \"fee_amount\": 0.0,\r\n \"pending_amount\": 0.0,\r\n \"pending_unfreeze_on\": null,\r\n \"description\": \"\",\r\n \"paid_on\": 1768115700,\r\n \"remote_paid_on\": 1768115700\r\n },\r\n \"issuer_details\": {\r\n \"website\": \"\",\r\n \"legal_street_address\": \"\",\r\n \"legal_country\": \"\",\r\n \"legal_city\": \"\",\r\n \"legal_zip_code\": \"\",\r\n \"bank_accounts\": [\r\n {}\r\n ],\r\n \"legal_name\": \"Testing\",\r\n \"brand_name\": \"Testing\",\r\n \"registration_number\": \"\",\r\n \"tax_number\": \"\"\r\n },\r\n \"transaction_data\": {\r\n \"payment_method\": \"\",\r\n \"flow\": \"payform\",\r\n \"extra\": {\r\n \"amount\": 1.0,\r\n \"masked_pan\": \"GOOGLEPAY-REDIRECT\"\r\n },\r\n \"country\": \"\",\r\n \"attempts\": [\r\n {\r\n \"client_ip\": \"183.83.53.41\",\r\n \"type\": \"execute\",\r\n \"payment_method\": \"GOOGLEPAY-REDIRECT\",\r\n \"flow\": \"payform\",\r\n \"successful\": true,\r\n \"country\": \"GOOGLEPAY-REDIRECT\",\r\n \"processing_time\": 1768115700,\r\n \"extra\": {\r\n \"amount\": 1.0,\r\n \"masked_pan\": \"GOOGLEPAY-REDIRECT\"\r\n }\r\n }\r\n ]\r\n },\r\n \"status\": \"PAYMENT_IN_PROCESS\",\r\n \"status_history\": [\r\n {\r\n \"status\": \"created\",\r\n \"timestamp\": 1768115700\r\n },\r\n {\r\n \"status\": \"pending_execute\",\r\n \"timestamp\": 1768115700\r\n },\r\n {\r\n \"status\": \"payment_in_process\",\r\n \"timestamp\": 1768115701\r\n }\r\n ],\r\n \"is_test\": false,\r\n \"brand_id\": \"59c5ed48-caf9-464a-ba54-26e1e02bc1bc\",\r\n \"send_receipt\": false,\r\n \"is_recurring_token\": false,\r\n \"skip_capture\": false,\r\n \"reference_generated\": \"PS363\",\r\n \"issued\": \"2026-01-11\",\r\n \"due\": 1768115700,\r\n \"refund_upto\": 1783664101,\r\n \"cc_descriptor\": \"\",\r\n \"fraudScore\": \"0\",\r\n \"trustScore\": \"1\",\r\n \"extraFee\": \"0\",\r\n \"pix_payload\": {},\r\n \"payInDetails\": {},\r\n \"paidOn\": 0,\r\n \"receivedAmt\": 0.0,\r\n \"taxAmount\": 0.0,\r\n \"surcharge\": 0.0,\r\n \"surchargeType\": \"\",\r\n \"sessionId\": \"\",\r\n \"refund_availability\": \"NONE\",\r\n \"refundable_amount\": 1.0,\r\n \"success_redirect\": \"https://your-redirect-url?issucces=true\",\r\n \"pending_redirect\": \"https://your-redirect-url?ispending=true\",\r\n \"failure_redirect\": \"https://your-redirect-url?isfailure=true\",\r\n \"success_callback\": \"https://your-webhook-url\",\r\n \"failure_callback\": \"https://your-webhook-url\"\r\n \"platform\": \"API\",\r\n \"created_from_ip\": \"183.83.53.41\",\r\n \"checkout_url\": \"https://api.choicepay.ca/payments/deb852445bd4b0fa6c4587f652174ab9/\",\r\n \"payoutProcess\": false\r\n}"},{"id":"97f642a0-8827-45ec-8ed9-aca662acfb97","name":"Purchase - failure","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer Token"}],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"email\": \"rahultest@gmail.com\",\r\n \"country\": \"GB\",\r\n \"city\": \"London\",\r\n \"stateCode\": \"RJ\",\r\n \"street_address\": \"10 New Burlington StreetApt. 214\",\r\n \"zip_code\": \"W1S 3BE\",\r\n \"date_of_birth\": \"1994-31-04\",\r\n \"phone\": \"+91 9634088561\",\r\n \"full_name\": \"Rahul Agarwal\"\r\n },\r\n \"purchase\": {\r\n \"currency\": \"EUR\",\r\n \"products\": [\r\n {\r\n \"name\": \"gaming cards \",\r\n \"price\": 10\r\n }\r\n ]\r\n },\r\n \"brand_id\": \"your-brandid\",\r\n \"paymentMethod\": \"GOOGLEPAY-REDIRECT\",\r\n \"success_redirect\": \"https://your-redirect-url?issucces=true\",\r\n \"pending_redirect\": \"https://your-redirect-url?ispending=true\",\r\n \"failure_redirect\": \"https://your-redirect-url?isfailure=true\",\r\n \"success_callback\": \"https://your-webhook-url\",\r\n \"failure_callback\": \"https://your-webhook-url\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/purchases"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"message\": \"Error Message\",\r\n \"code\": \"error_code\"\r\n}"}],"_postman_id":"2b3ad128-9889-4cd0-a2e2-129edc8ab63f"},{"name":"Session","id":"8344a78a-4353-4f18-84c9-3b990e3b3775","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/createSession","description":"

OVERVIEW

The createSession API is designed to initiate a payment session for a customer after their profile has been created via the createCustomer API. The session is automatically generated at the backend on the merchant’s checkout URL. This session allows the customer to continue with their transaction without having to manually interact with the session URL, and ensures the session remains active until the payment is completed or the session expires.

This API improves the user experience by reducing transaction failures and enhancing the overall payment process, thus reducing transaction churn rates.

Mandatory Parameters

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Type	Description	Example
customerId	String	The unique ID of the customer (generated from createCustomer).	6731a609b6bb5a43ad66c4a6

Usage Flow

Customer completes the createCustomer API: Once the customer is created via the createCustomer API, the merchant proceeds to call the createSession API to generate a session.
\n
Merchant sends createSession request: The merchant sends a POST request to the createSession API with the customer’s customerId and the merchant’s brandId.
\n
Session created automatically on the checkout URL: Paybomb creates the session and associates it with the merchant’s checkout page. This session remains active on the backend, allowing the customer to continue the payment process without interruption.
\n
Customer proceeds to checkout: The customer is redirected to the checkout page as part of the merchant's payment flow, where the session is automatically validated. The session remains active for a set period, allowing the customer to complete the payment without needing to manually interact with the session URL.
\n
Session Expiry: The session expires after the set expiration time (expiryOn), ensuring the payment process is completed within the defined window. Default is 15 mins from the creation time.
\n

Benefits

Seamless Checkout: The session URL is automatically generated and active at the backend, ensuring a smoother and uninterrupted customer experience.
\n
Reduced Transaction Failures: By ensuring the session remains active during the payment process, the chances of transaction failures due to session timeouts are minimized.
\n
Improved User Experience: The customer does not need to click on a session URL or navigate away from the page, leading to faster and more secure payment processing.
\n

\n","urlObject":{"path":["createSession"],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"2a26d7a5-92c0-482f-a444-add1c380700e","name":"Success","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"*/*","type":"text"},{"key":"BrandId","value":"brand_id_value","description":"it is mandatory to pass the BrandId in header for each createSession request. ","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"customerId\": \"69034a5a61b460084d20c23b\",\r\n \"merchantRef\": \"rahultestcustomer1@paybomb.tech\", // optional\r\n \"currency\": \"EUR\",\r\n \"products\": [\r\n {\r\n \"name\": \"Product1\",\r\n \"price\": \"10\"\r\n },\r\n {\r\n \"name\": \"Product2\",\r\n \"price\": \"12\"\r\n }\r\n ],\r\n \"totalAmount\": \"22\", // optional, but if present have precedence over sum of prices.\r\n \"paymentMethod\": \"GOOGLEPAY-REDIRECT\", //optional\r\n \"success_redirect\": \"https://your-redirect-url?issucces=true\",\r\n \"pending_redirect\": \"https://your-redirect-url?ispending=true\",\r\n \"failure_redirect\": \"https://your-redirect-url?isfailure=true\",\r\n \"success_callback\": \"https://your-webhook-url\",\r\n \"failure_callback\": \"https://your-webhook-url\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/createSession"},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"sessionUrl\": \"https://api.choicepay.ca/payment-session/6963533a0a18ea65153a81e7/\",\r\n \"brandId\": \"brand_id_value\",\r\n \"customerId\": \"69034a5a61b460084d20c23b\",\r\n \"sessionId\": \"6963533a0a18ea65153a81e7\",\r\n \"expiryOn\": 1768117950,\r\n \"createdOn\": 1768117050\r\n}"},{"id":"b5fd93db-4bd9-428d-9731-57bc5bd69886","name":"Invalid Session","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"*/*","type":"text"},{"key":"BrandId","value":"brand_id_value","description":"it is mandatory to pass the BrandId in header for each createSession request. ","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"customerId\": \"69034a5a61b460084d20c23b\",\r\n \"merchantRef\": \"rahultestcustomer1@paybomb.tech\", // optional\r\n \"currency\": \"EUR\",\r\n \"products\": [\r\n {\r\n \"name\": \"Product1\",\r\n \"price\": \"10\"\r\n },\r\n {\r\n \"name\": \"Product2\",\r\n \"price\": \"12\"\r\n }\r\n ],\r\n \"totalAmount\": \"22\", // optional, but if present have precedence over sum of prices.\r\n \"paymentMethod\": \"GOOGLEPAY-REDIRECT\", //optional\r\n \"success_redirect\": \"https://your-redirect-url?issucces=true\",\r\n \"pending_redirect\": \"https://your-redirect-url?ispending=true\",\r\n \"failure_redirect\": \"https://your-redirect-url?isfailure=true\",\r\n \"success_callback\": \"https://your-webhook-url\",\r\n \"failure_callback\": \"https://your-webhook-url\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.paybomb.net/api/v1/createSession"},"status":"Bad Request","code":400,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"message\": \"Customer does not exist with this Customer Id\",\r\n \"code\": \"Customer Id is invalid\"\r\n}"}],"_postman_id":"8344a78a-4353-4f18-84c9-3b990e3b3775"},{"name":"Get Status","id":"79c53474-af6f-46df-9213-c7d659bac7a3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"url":"https://app.paybomb.tech/api/v1/purchases/{purchaseId}/","description":"

This API tells you about all the details of a purchase (PayIn), including its history

Mandatory

you need to pass the PurchaseID in the API URL

Possible Value of Status

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Notes
paid	Transaction Successful
payment_in_process	Payment is under Processing
expired	Purchase has Expired.
error	Transaction has Failed.

Response Examples

In the response examples you can see instances of both Paid and Error Status purchases.

Error Details

If there are any issues on the Purchase you can get more details from the transaction_data.attempts.error attribute of the response object

Errors

If there are any errors then it'll be in the format of :

{\n    \"message\": \"descriptive error message\",\n    \"code\": \"error_code\"\n}\n\n

Please see the Status Code section for further details.

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"7e4346a7-1c22-4378-bb36-3f70a3998bbd","id":"7e4346a7-1c22-4378-bb36-3f70a3998bbd","name":"APIs","type":"folder"}},"urlObject":{"path":["purchases","{purchaseId}",""],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"b07253b9-59cd-4eff-8e75-3e01adb33d1c","name":"Purchase - success","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer Token"}],"url":"https://app.paybomb.tech/api/v1/purchases/{purchaseId}/"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"purchaseId\": \"69634df44549cbd3547ac750\",\r\n \"client\": {\r\n \"customerId\": \"NA\",\r\n \"email\": \"rahultest@gmail.com\",\r\n \"phone\": \"+91 9634088561\",\r\n \"full_name\": \"Rahul Agarwal\",\r\n \"date_of_birth\": \"1994-31-04\",\r\n \"street_address\": \"10 New Burlington StreetApt. 214\",\r\n \"country\": \"GB\",\r\n \"city\": \"London\",\r\n \"zip_code\": \"W1S 3BE\",\r\n \"cc\": [],\r\n \"bcc\": [],\r\n \"stateCode\": \"RJ\"\r\n },\r\n \"updated_on\": 1768115701,\r\n \"type\": \"purchase\",\r\n \"paymentMethod\": \"GOOGLEPAY-REDIRECT\",\r\n \"amountUnit\": \"MAJOR\",\r\n \"errorMsg\": \"\",\r\n \"errorCode\": \"NA\",\r\n \"force_recurring\": false,\r\n \"created_on\": 1768115700,\r\n \"merchantRef\": \"69634df44549cbd3547ac750\",\r\n \"purchase\": {\r\n \"currency\": \"EUR\",\r\n \"products\": [\r\n {\r\n \"name\": \"gaming cards\",\r\n \"quantity\": 1.0,\r\n \"price\": 1.0,\r\n \"discount\": 0,\r\n \"tax_percent\": \"0.00\"\r\n }\r\n ],\r\n \"total\": 1.0,\r\n \"requestAmount\": 1.0,\r\n \"language\": \"en\",\r\n \"notes\": \"\",\r\n \"debt\": 0,\r\n \"total_formatted\": 1.0,\r\n \"taxAmount\": 0.0,\r\n \"taxPercent\": 0.0,\r\n \"request_client_details\": [],\r\n \"email_message\": \"\"\r\n },\r\n \"payment\": {\r\n \"is_outgoing\": false,\r\n \"payment_type\": \"PURCHASE\",\r\n \"amount\": 1.0,\r\n \"currency\": \"EUR\",\r\n \"net_amount\": 1.0,\r\n \"fee_amount\": 0.0,\r\n \"pending_amount\": 0.0,\r\n \"pending_unfreeze_on\": null,\r\n \"description\": \"\",\r\n \"paid_on\": 1768115700,\r\n \"remote_paid_on\": 1768115700\r\n },\r\n \"issuer_details\": {\r\n \"website\": \"\",\r\n \"legal_street_address\": \"\",\r\n \"legal_country\": \"\",\r\n \"legal_city\": \"\",\r\n \"legal_zip_code\": \"\",\r\n \"bank_accounts\": [\r\n {}\r\n ],\r\n \"legal_name\": \"Testing\",\r\n \"brand_name\": \"Testing\",\r\n \"registration_number\": \"\",\r\n \"tax_number\": \"\"\r\n },\r\n \"transaction_data\": {\r\n \"payment_method\": \"\",\r\n \"flow\": \"payform\",\r\n \"extra\": {\r\n \"amount\": 1.0,\r\n \"masked_pan\": \"GOOGLEPAY-REDIRECT\"\r\n },\r\n \"country\": \"\",\r\n \"attempts\": [\r\n {\r\n \"client_ip\": \"183.83.53.41\",\r\n \"type\": \"execute\",\r\n \"payment_method\": \"GOOGLEPAY-REDIRECT\",\r\n \"flow\": \"payform\",\r\n \"successful\": true,\r\n \"country\": \"GOOGLEPAY-REDIRECT\",\r\n \"processing_time\": 1768115700,\r\n \"extra\": {\r\n \"amount\": 1.0,\r\n \"masked_pan\": \"GOOGLEPAY-REDIRECT\"\r\n }\r\n }\r\n ]\r\n },\r\n \"status\": \"PAID\",\r\n \"status_history\": [\r\n {\r\n \"status\": \"created\",\r\n \"timestamp\": 1768115700\r\n },\r\n {\r\n \"status\": \"pending_execute\",\r\n \"timestamp\": 1768115700\r\n },\r\n {\r\n \"status\": \"payment_in_process\",\r\n \"timestamp\": 1768115701\r\n },\r\n {\r\n \"status\": \"paid\",\r\n \"timestamp\": 1768115701\r\n }\r\n ],\r\n \"is_test\": false,\r\n \"brand_id\": \"59c5ed48-caf9-464a-ba54-26e1e02bc1bc\",\r\n \"send_receipt\": false,\r\n \"is_recurring_token\": false,\r\n \"skip_capture\": false,\r\n \"reference_generated\": \"PS363\",\r\n \"issued\": \"2026-01-11\",\r\n \"due\": 1768115700,\r\n \"refund_upto\": 1783664101,\r\n \"cc_descriptor\": \"\",\r\n \"fraudScore\": \"0\",\r\n \"trustScore\": \"1\",\r\n \"extraFee\": \"0\",\r\n \"pix_payload\": {},\r\n \"payInDetails\": {},\r\n \"paidOn\": 0,\r\n \"receivedAmt\": 0.0,\r\n \"taxAmount\": 0.0,\r\n \"surcharge\": 0.0,\r\n \"surchargeType\": \"\",\r\n \"sessionId\": \"\",\r\n \"refund_availability\": \"NONE\",\r\n \"refundable_amount\": 1.0,\r\n \"success_redirect\": \"https://your-redirect-url?issucces=true\",\r\n \"pending_redirect\": \"https://your-redirect-url?ispending=true\",\r\n \"failure_redirect\": \"https://your-redirect-url?isfailure=true\",\r\n \"success_callback\": \"https://your-webhook-url\",\r\n \"failure_callback\": \"https://your-webhook-url\"\r\n \"platform\": \"API\",\r\n \"created_from_ip\": \"183.83.53.41\",\r\n \"checkout_url\": \"https://api.choicepay.ca/payments/deb852445bd4b0fa6c4587f652174ab9/\",\r\n \"payoutProcess\": false\r\n}"},{"id":"8cd73b95-1ee7-4012-9ca5-2fccf71a5791","name":"Purchase - failure","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"url":"https://app.paybomb.tech/api/v1/purchases/{purchaseId}/"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"message\": \"Error Message\",\r\n \"code\": \"error_code\"\r\n}"}],"_postman_id":"79c53474-af6f-46df-9213-c7d659bac7a3"}],"id":"7e4346a7-1c22-4378-bb36-3f70a3998bbd","description":"

API Flow

The merchant initiates the purchase via the create purchase API and passing the appropriate payment method. If successful, they receive a checkout URL in the response JSON.
\n
Upon utilizing the checkout URL, the user will be presented with a screen where he will be shown a button to pay via Googlepay.
\n
After clicking the button, the user will see all the cards stored in the google wallet and he can choose one of the cards to make the purchase.
\n
After a successful or failed payment by the end user, an appropriate webhook would be sent to the merchant. The user would also be redirected to the appropriate redirect URL.
\n

Overview

Apple Pay enables customers to make payments on a merchant’s website or app using credit or debit cards securely stored in their Apple Wallet. During checkout, Apple Pay presents a payment sheet where customers can select their preferred card and confirm the payment using Touch ID, Face ID, or their device passcode.

Customers add their payment cards to Apple Wallet, which securely stores the card information. When making a purchase, they simply select Apple Pay as the payment method and complete the transaction using a saved card—eliminating the need to manually enter card details for each payment.

Features

Convenient: Customers can pay using cards already saved in Apple Pay, reducing checkout friction.
\n
Secure: Uses device-specific tokenization (DPAN/MPAN) to protect sensitive card data during the payment process.
\n
3D Secure support: The payment handle created through the integration supports 3D Secure authentication when required, ensuring secure transactions.
\n
Wide coverage: Supported across multiple regions and currencies.
\n

By integrating Apple Pay through the Paybomb API, you can provide your customers with a fast, secure, and seamless payment experience.

Note

This is a redirection-based payment method. During the payment flow, the user is redirected to a third-party application or interface, where the Apple Pay button is displayed to complete the payment.

\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"1b7aceca-e751-4ff9-b22b-d6d0e0d7e6ef"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"9ca5d849-b4ce-4be2-b065-4dff0c437490"}}],"_postman_id":"cf44b219-2bea-459a-bdf6-eb6134ae883d"},{"name":"APIs","item":[{"name":"Purchases","id":"464b5ca3-ff57-43ef-9117-15f2c675f744","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer Token"}],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"email\": \"rahultest@gmail.com\",\r\n \"country\": \"GB\",\r\n \"city\": \"London\",\r\n \"stateCode\": \"RJ\",\r\n \"street_address\": \"10 New Burlington StreetApt. 214\",\r\n \"zip_code\": \"W1S 3BE\",\r\n \"date_of_birth\": \"1994-31-04\",\r\n \"phone\": \"+91 9634088561\",\r\n \"full_name\": \"Rahul Agarwal\"\r\n },\r\n \"purchase\": {\r\n \"currency\": \"EUR\",\r\n \"products\": [\r\n {\r\n \"name\": \"gaming cards \",\r\n \"price\": 10\r\n }\r\n ]\r\n },\r\n \"brand_id\": \"your-brandid\",\r\n \"paymentMethod\": \"APPLEPAY-REDIRECT\",\r\n \"success_redirect\": \"https://your-redirect-url?issucces=true\",\r\n \"pending_redirect\": \"https://your-redirect-url?ispending=true\",\r\n \"failure_redirect\": \"https://your-redirect-url?isfailure=true\",\r\n \"success_callback\": \"https://your-webhook-url\",\r\n \"failure_callback\": \"https://your-webhook-url\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/purchases/","description":"

To Initiate a payment, the very first call to make is /purchases with the required data in the request body.

To generate a Purchase, you are required to provide the Brand ID (in the request body) and API key (in the header) Both can be located in the Dashboard section of your merchant account login.

The request body structure is shown on the request body of the example request shown here.

The following (see table below) are the mandatory parameters that are required to create a purchase request.

Parameters in the request body:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Notes
client.full_name	Conditional. But Recommended to pass the complete name of the client. Atleast 2 words recommended.
client.email	Conditional. But Recommended to pass a correct email id.
paymentMethod	Conditional. Mandatory if you are not using Paybomb Cashier. Else Non Mandatory. Value: APPLEPAY-REDIRECT
purchase.currency	Mandatory. ISO 4217 code for currency you want to send the transaction in. This should be 'BRL' for PIX.
purchase.products.name	Mandatory.
purchase.products.price	Mandatory. Price in decimal format upto 2 decimals. example 1: EUR 5 , should be sent as 5.00 example 2: USD 10 and 37 cents , should be sent as 10.37
brand_id	Mandatory. Obtain from Dashboard section of your merchant account login.
success_redirect	Mandatory. URL to send the user if the transactions is successful.
pending_redirect	Mandatory. URL to send the user if the transactions is in progress state.
failure_redirect	Mandatory URL to send the user if the transactions has failed.

Optional Parameters

expireInMin

merchantRef

The merchantRef parameter, although not mandatory, is strongly advised for merchants to specify. Its inclusion offers two significant advantages for the merchant:

Prevention of Duplicate Requests: When a merchantRef is utilized, it acts as a unique identifier. This means that if a second purchase request is made using the same merchantRef (reference number), the system will recognize it and prevent duplicate transactions from occurring. This prevents unintended or duplicate purchases.
\n
Facilitation of Transaction Retrieval: In situations where the response from the initial purchase request times out or the 'purchaseId' isn't received, having the merchantRef allows the merchant to retrieve detailed transaction information. This ensures they can track and access the specific purchase details related to that reference, even if the immediate response was not received.
\n

However, if the merchant does not specify the 'merchantRef' parameter, the platform will automatically assign and use an internal 'purchaseId' as a reference for that transaction.

paymentMethod

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"fbcf6289-1ca0-4e35-9756-6ea0c5abb7a8","id":"fbcf6289-1ca0-4e35-9756-6ea0c5abb7a8","name":"APIs","type":"folder"}},"urlObject":{"path":["purchases",""],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"fd231098-e65d-43a8-95f6-747b2eb16e6f","name":"Purchase - success","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer Token"}],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"email\": \"rahultest@gmail.com\",\r\n \"country\": \"GB\",\r\n \"city\": \"London\",\r\n \"stateCode\": \"RJ\",\r\n \"street_address\": \"10 New Burlington StreetApt. 214\",\r\n \"zip_code\": \"W1S 3BE\",\r\n \"date_of_birth\": \"1994-31-04\",\r\n \"phone\": \"+91 9634088561\",\r\n \"full_name\": \"Rahul Agarwal\"\r\n },\r\n \"purchase\": {\r\n \"currency\": \"EUR\",\r\n \"products\": [\r\n {\r\n \"name\": \"gaming cards \",\r\n \"price\": 10\r\n }\r\n ]\r\n },\r\n \"brand_id\": \"your-brandid\",\r\n \"paymentMethod\": \"APPLEPAY-REDIRECT\",\r\n \"success_redirect\": \"https://your-redirect-url?issucces=true\",\r\n \"pending_redirect\": \"https://your-redirect-url?ispending=true\",\r\n \"failure_redirect\": \"https://your-redirect-url?isfailure=true\",\r\n \"success_callback\": \"https://your-webhook-url\",\r\n \"failure_callback\": \"https://your-webhook-url\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/purchases"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"purchaseId\": \"69634df44549cbd3547ac750\",\r\n \"client\": {\r\n \"customerId\": \"NA\",\r\n \"email\": \"rahultest@gmail.com\",\r\n \"phone\": \"+91 9634088561\",\r\n \"full_name\": \"Rahul Agarwal\",\r\n \"date_of_birth\": \"1994-31-04\",\r\n \"street_address\": \"10 New Burlington StreetApt. 214\",\r\n \"country\": \"GB\",\r\n \"city\": \"London\",\r\n \"zip_code\": \"W1S 3BE\",\r\n \"cc\": [],\r\n \"bcc\": [],\r\n \"stateCode\": \"RJ\"\r\n },\r\n \"updated_on\": 1768115701,\r\n \"type\": \"purchase\",\r\n \"paymentMethod\": \"APPLEPAY-REDIRECT\",\r\n \"amountUnit\": \"MAJOR\",\r\n \"errorMsg\": \"\",\r\n \"errorCode\": \"NA\",\r\n \"force_recurring\": false,\r\n \"created_on\": 1768115700,\r\n \"merchantRef\": \"69634df44549cbd3547ac750\",\r\n \"purchase\": {\r\n \"currency\": \"EUR\",\r\n \"products\": [\r\n {\r\n \"name\": \"gaming cards\",\r\n \"quantity\": 1.0,\r\n \"price\": 1.0,\r\n \"discount\": 0,\r\n \"tax_percent\": \"0.00\"\r\n }\r\n ],\r\n \"total\": 1.0,\r\n \"requestAmount\": 1.0,\r\n \"language\": \"en\",\r\n \"notes\": \"\",\r\n \"debt\": 0,\r\n \"total_formatted\": 1.0,\r\n \"taxAmount\": 0.0,\r\n \"taxPercent\": 0.0,\r\n \"request_client_details\": [],\r\n \"email_message\": \"\"\r\n },\r\n \"payment\": {\r\n \"is_outgoing\": false,\r\n \"payment_type\": \"PURCHASE\",\r\n \"amount\": 1.0,\r\n \"currency\": \"EUR\",\r\n \"net_amount\": 1.0,\r\n \"fee_amount\": 0.0,\r\n \"pending_amount\": 0.0,\r\n \"pending_unfreeze_on\": null,\r\n \"description\": \"\",\r\n \"paid_on\": 1768115700,\r\n \"remote_paid_on\": 1768115700\r\n },\r\n \"issuer_details\": {\r\n \"website\": \"\",\r\n \"legal_street_address\": \"\",\r\n \"legal_country\": \"\",\r\n \"legal_city\": \"\",\r\n \"legal_zip_code\": \"\",\r\n \"bank_accounts\": [\r\n {}\r\n ],\r\n \"legal_name\": \"Testing\",\r\n \"brand_name\": \"Testing\",\r\n \"registration_number\": \"\",\r\n \"tax_number\": \"\"\r\n },\r\n \"transaction_data\": {\r\n \"payment_method\": \"\",\r\n \"flow\": \"payform\",\r\n \"extra\": {\r\n \"amount\": 1.0,\r\n \"masked_pan\": \"APPLEPAY-REDIRECT\"\r\n },\r\n \"country\": \"\",\r\n \"attempts\": [\r\n {\r\n \"client_ip\": \"183.83.53.41\",\r\n \"type\": \"execute\",\r\n \"payment_method\": \"APPLEPAY-REDIRECT\",\r\n \"flow\": \"payform\",\r\n \"successful\": true,\r\n \"country\": \"APPLEPAY-REDIRECT\",\r\n \"processing_time\": 1768115700,\r\n \"extra\": {\r\n \"amount\": 1.0,\r\n \"masked_pan\": \"APPLEPAY-REDIRECT\"\r\n }\r\n }\r\n ]\r\n },\r\n \"status\": \"PAYMENT_IN_PROCESS\",\r\n \"status_history\": [\r\n {\r\n \"status\": \"created\",\r\n \"timestamp\": 1768115700\r\n },\r\n {\r\n \"status\": \"pending_execute\",\r\n \"timestamp\": 1768115700\r\n },\r\n {\r\n \"status\": \"payment_in_process\",\r\n \"timestamp\": 1768115701\r\n }\r\n ],\r\n \"is_test\": false,\r\n \"brand_id\": \"59c5ed48-caf9-464a-ba54-26e1e02bc1bc\",\r\n \"send_receipt\": false,\r\n \"is_recurring_token\": false,\r\n \"skip_capture\": false,\r\n \"reference_generated\": \"PS363\",\r\n \"issued\": \"2026-01-11\",\r\n \"due\": 1768115700,\r\n \"refund_upto\": 1783664101,\r\n \"cc_descriptor\": \"\",\r\n \"fraudScore\": \"0\",\r\n \"trustScore\": \"1\",\r\n \"extraFee\": \"0\",\r\n \"pix_payload\": {},\r\n \"payInDetails\": {},\r\n \"paidOn\": 0,\r\n \"receivedAmt\": 0.0,\r\n \"taxAmount\": 0.0,\r\n \"surcharge\": 0.0,\r\n \"surchargeType\": \"\",\r\n \"sessionId\": \"\",\r\n \"refund_availability\": \"NONE\",\r\n \"refundable_amount\": 1.0,\r\n \"success_redirect\": \"https://your-redirect-url?issucces=true\",\r\n \"pending_redirect\": \"https://your-redirect-url?ispending=true\",\r\n \"failure_redirect\": \"https://your-redirect-url?isfailure=true\",\r\n \"success_callback\": \"https://your-webhook-url\",\r\n \"failure_callback\": \"https://your-webhook-url\"\r\n \"platform\": \"API\",\r\n \"created_from_ip\": \"183.83.53.41\",\r\n \"checkout_url\": \"https://api.choicepay.ca/payments/deb852445bd4b0fa6c4587f652174ab9/\",\r\n \"payoutProcess\": false\r\n}"},{"id":"d49baa78-2246-4173-bd6e-d24679030580","name":"Purchase - failure","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer Token"}],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"email\": \"rahultest@gmail.com\",\r\n \"country\": \"GB\",\r\n \"city\": \"London\",\r\n \"stateCode\": \"RJ\",\r\n \"street_address\": \"10 New Burlington StreetApt. 214\",\r\n \"zip_code\": \"W1S 3BE\",\r\n \"date_of_birth\": \"1994-31-04\",\r\n \"phone\": \"+91 9634088561\",\r\n \"full_name\": \"Rahul Agarwal\"\r\n },\r\n \"purchase\": {\r\n \"currency\": \"EUR\",\r\n \"products\": [\r\n {\r\n \"name\": \"gaming cards \",\r\n \"price\": 10\r\n }\r\n ]\r\n },\r\n \"brand_id\": \"your-brandid\",\r\n \"paymentMethod\": \"APPLEPAY-REDIRECT\",\r\n \"success_redirect\": \"https://your-redirect-url?issucces=true\",\r\n \"pending_redirect\": \"https://your-redirect-url?ispending=true\",\r\n \"failure_redirect\": \"https://your-redirect-url?isfailure=true\",\r\n \"success_callback\": \"https://your-webhook-url\",\r\n \"failure_callback\": \"https://your-webhook-url\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/purchases"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"message\": \"Error Message\",\r\n \"code\": \"error_code\"\r\n}"}],"_postman_id":"464b5ca3-ff57-43ef-9117-15f2c675f744"},{"name":"Session","id":"9af05d11-2903-49e4-b2ec-5c3c3d398941","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/createSession","description":"

OVERVIEW

This API improves the user experience by reducing transaction failures and enhancing the overall payment process, thus reducing transaction churn rates.

Mandatory Parameters

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Type	Description	Example
customerId	String	The unique ID of the customer (generated from createCustomer).	6731a609b6bb5a43ad66c4a6

Usage Flow

Customer completes the createCustomer API: Once the customer is created via the createCustomer API, the merchant proceeds to call the createSession API to generate a session.
\n
Merchant sends createSession request: The merchant sends a POST request to the createSession API with the customer’s customerId and the merchant’s brandId.
\n
Session created automatically on the checkout URL: Paybomb creates the session and associates it with the merchant’s checkout page. This session remains active on the backend, allowing the customer to continue the payment process without interruption.
\n
Customer proceeds to checkout: The customer is redirected to the checkout page as part of the merchant's payment flow, where the session is automatically validated. The session remains active for a set period, allowing the customer to complete the payment without needing to manually interact with the session URL.
\n
Session Expiry: The session expires after the set expiration time (expiryOn), ensuring the payment process is completed within the defined window. Default is 15 mins from the creation time.
\n

Benefits

Seamless Checkout: The session URL is automatically generated and active at the backend, ensuring a smoother and uninterrupted customer experience.
\n
Reduced Transaction Failures: By ensuring the session remains active during the payment process, the chances of transaction failures due to session timeouts are minimized.
\n
Improved User Experience: The customer does not need to click on a session URL or navigate away from the page, leading to faster and more secure payment processing.
\n

\n","urlObject":{"path":["createSession"],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"1499cab7-5993-47b4-bdcc-f1bc371abbb9","name":"Success","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"*/*","type":"text"},{"key":"BrandId","value":"brand_id_value","description":"it is mandatory to pass the BrandId in header for each createSession request. ","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"customerId\": \"69034a5a61b460084d20c23b\",\r\n \"merchantRef\": \"rahultestcustomer1@paybomb.tech\", // optional\r\n \"currency\": \"EUR\",\r\n \"products\": [\r\n {\r\n \"name\": \"Product1\",\r\n \"price\": \"10\"\r\n },\r\n {\r\n \"name\": \"Product2\",\r\n \"price\": \"12\"\r\n }\r\n ],\r\n \"totalAmount\": \"22\", // optional, but if present have precedence over sum of prices.\r\n \"paymentMethod\": \"APPLEPAY-REDIRECT\", //optional\r\n \"success_redirect\": \"https://your-redirect-url?issucces=true\",\r\n \"pending_redirect\": \"https://your-redirect-url?ispending=true\",\r\n \"failure_redirect\": \"https://your-redirect-url?isfailure=true\",\r\n \"success_callback\": \"https://your-webhook-url\",\r\n \"failure_callback\": \"https://your-webhook-url\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/createSession"},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"sessionUrl\": \"https://api.choicepay.ca/payment-session/6963533a0a18ea65153a81e7/\",\r\n \"brandId\": \"brand_id_value\",\r\n \"customerId\": \"69034a5a61b460084d20c23b\",\r\n \"sessionId\": \"6963533a0a18ea65153a81e7\",\r\n \"expiryOn\": 1768117950,\r\n \"createdOn\": 1768117050\r\n}"},{"id":"2aac2330-2685-4647-903e-2996b0124adc","name":"Invalid Session","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"*/*","type":"text"},{"key":"BrandId","value":"brand_id_value","description":"it is mandatory to pass the BrandId in header for each createSession request. ","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"customerId\": \"69034a5a61b460084d20c23b\",\r\n \"merchantRef\": \"rahultestcustomer1@paybomb.tech\", // optional\r\n \"currency\": \"EUR\",\r\n \"products\": [\r\n {\r\n \"name\": \"Product1\",\r\n \"price\": \"10\"\r\n },\r\n {\r\n \"name\": \"Product2\",\r\n \"price\": \"12\"\r\n }\r\n ],\r\n \"totalAmount\": \"22\", // optional, but if present have precedence over sum of prices.\r\n \"paymentMethod\": \"APPLEPAY-REDIRECT\", //optional\r\n \"success_redirect\": \"https://your-redirect-url?issucces=true\",\r\n \"pending_redirect\": \"https://your-redirect-url?ispending=true\",\r\n \"failure_redirect\": \"https://your-redirect-url?isfailure=true\",\r\n \"success_callback\": \"https://your-webhook-url\",\r\n \"failure_callback\": \"https://your-webhook-url\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.paybomb.net/api/v1/createSession"},"status":"Bad Request","code":400,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"message\": \"Customer does not exist with this Customer Id\",\r\n \"code\": \"Customer Id is invalid\"\r\n}"}],"_postman_id":"9af05d11-2903-49e4-b2ec-5c3c3d398941"},{"name":"Get Status","id":"e6dd61c4-6ca3-4cb3-bc16-76a6467d083e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"url":"https://app.paybomb.tech/api/v1/purchases/{purchaseId}/","description":"

This API tells you about all the details of a purchase (PayIn), including its history

Mandatory

you need to pass the PurchaseID in the API URL

Possible Value of Status

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Notes
paid	Transaction Successful
payment_in_process	Payment is under Processing
expired	Purchase has Expired.
error	Transaction has Failed.

Response Examples

In the response examples you can see instances of both Paid and Error Status purchases.

Error Details

If there are any issues on the Purchase you can get more details from the transaction_data.attempts.error attribute of the response object

Errors

If there are any errors then it'll be in the format of :

{\n    \"message\": \"descriptive error message\",\n    \"code\": \"error_code\"\n}\n\n

Please see the Status Code section for further details.

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"fbcf6289-1ca0-4e35-9756-6ea0c5abb7a8","id":"fbcf6289-1ca0-4e35-9756-6ea0c5abb7a8","name":"APIs","type":"folder"}},"urlObject":{"path":["purchases","{purchaseId}",""],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"7ad37dad-df16-473e-81cc-c584704820a2","name":"Purchase - success","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer Token"}],"url":"https://app.paybomb.tech/api/v1/purchases/{purchaseId}/"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"purchaseId\": \"69634df44549cbd3547ac750\",\r\n \"client\": {\r\n \"customerId\": \"NA\",\r\n \"email\": \"rahultest@gmail.com\",\r\n \"phone\": \"+91 9634088561\",\r\n \"full_name\": \"Rahul Agarwal\",\r\n \"date_of_birth\": \"1994-31-04\",\r\n \"street_address\": \"10 New Burlington StreetApt. 214\",\r\n \"country\": \"GB\",\r\n \"city\": \"London\",\r\n \"zip_code\": \"W1S 3BE\",\r\n \"cc\": [],\r\n \"bcc\": [],\r\n \"stateCode\": \"RJ\"\r\n },\r\n \"updated_on\": 1768115701,\r\n \"type\": \"purchase\",\r\n \"paymentMethod\": \"APPLEPAY-REDIRECT\",\r\n \"amountUnit\": \"MAJOR\",\r\n \"errorMsg\": \"\",\r\n \"errorCode\": \"NA\",\r\n \"force_recurring\": false,\r\n \"created_on\": 1768115700,\r\n \"merchantRef\": \"69634df44549cbd3547ac750\",\r\n \"purchase\": {\r\n \"currency\": \"EUR\",\r\n \"products\": [\r\n {\r\n \"name\": \"gaming cards\",\r\n \"quantity\": 1.0,\r\n \"price\": 1.0,\r\n \"discount\": 0,\r\n \"tax_percent\": \"0.00\"\r\n }\r\n ],\r\n \"total\": 1.0,\r\n \"requestAmount\": 1.0,\r\n \"language\": \"en\",\r\n \"notes\": \"\",\r\n \"debt\": 0,\r\n \"total_formatted\": 1.0,\r\n \"taxAmount\": 0.0,\r\n \"taxPercent\": 0.0,\r\n \"request_client_details\": [],\r\n \"email_message\": \"\"\r\n },\r\n \"payment\": {\r\n \"is_outgoing\": false,\r\n \"payment_type\": \"PURCHASE\",\r\n \"amount\": 1.0,\r\n \"currency\": \"EUR\",\r\n \"net_amount\": 1.0,\r\n \"fee_amount\": 0.0,\r\n \"pending_amount\": 0.0,\r\n \"pending_unfreeze_on\": null,\r\n \"description\": \"\",\r\n \"paid_on\": 1768115700,\r\n \"remote_paid_on\": 1768115700\r\n },\r\n \"issuer_details\": {\r\n \"website\": \"\",\r\n \"legal_street_address\": \"\",\r\n \"legal_country\": \"\",\r\n \"legal_city\": \"\",\r\n \"legal_zip_code\": \"\",\r\n \"bank_accounts\": [\r\n {}\r\n ],\r\n \"legal_name\": \"Testing\",\r\n \"brand_name\": \"Testing\",\r\n \"registration_number\": \"\",\r\n \"tax_number\": \"\"\r\n },\r\n \"transaction_data\": {\r\n \"payment_method\": \"\",\r\n \"flow\": \"payform\",\r\n \"extra\": {\r\n \"amount\": 1.0,\r\n \"masked_pan\": \"APPLEPAY-REDIRECT\"\r\n },\r\n \"country\": \"\",\r\n \"attempts\": [\r\n {\r\n \"client_ip\": \"183.83.53.41\",\r\n \"type\": \"execute\",\r\n \"payment_method\": \"APPLEPAY-REDIRECT\",\r\n \"flow\": \"payform\",\r\n \"successful\": true,\r\n \"country\": \"APPLEPAY-REDIRECT\",\r\n \"processing_time\": 1768115700,\r\n \"extra\": {\r\n \"amount\": 1.0,\r\n \"masked_pan\": \"APPLEPAY-REDIRECT\"\r\n }\r\n }\r\n ]\r\n },\r\n \"status\": \"PAID\",\r\n \"status_history\": [\r\n {\r\n \"status\": \"created\",\r\n \"timestamp\": 1768115700\r\n },\r\n {\r\n \"status\": \"pending_execute\",\r\n \"timestamp\": 1768115700\r\n },\r\n {\r\n \"status\": \"payment_in_process\",\r\n \"timestamp\": 1768115701\r\n },\r\n {\r\n \"status\": \"paid\",\r\n \"timestamp\": 1768115701\r\n }\r\n ],\r\n \"is_test\": false,\r\n \"brand_id\": \"59c5ed48-caf9-464a-ba54-26e1e02bc1bc\",\r\n \"send_receipt\": false,\r\n \"is_recurring_token\": false,\r\n \"skip_capture\": false,\r\n \"reference_generated\": \"PS363\",\r\n \"issued\": \"2026-01-11\",\r\n \"due\": 1768115700,\r\n \"refund_upto\": 1783664101,\r\n \"cc_descriptor\": \"\",\r\n \"fraudScore\": \"0\",\r\n \"trustScore\": \"1\",\r\n \"extraFee\": \"0\",\r\n \"pix_payload\": {},\r\n \"payInDetails\": {},\r\n \"paidOn\": 0,\r\n \"receivedAmt\": 0.0,\r\n \"taxAmount\": 0.0,\r\n \"surcharge\": 0.0,\r\n \"surchargeType\": \"\",\r\n \"sessionId\": \"\",\r\n \"refund_availability\": \"NONE\",\r\n \"refundable_amount\": 1.0,\r\n \"success_redirect\": \"https://your-redirect-url?issucces=true\",\r\n \"pending_redirect\": \"https://your-redirect-url?ispending=true\",\r\n \"failure_redirect\": \"https://your-redirect-url?isfailure=true\",\r\n \"success_callback\": \"https://your-webhook-url\",\r\n \"failure_callback\": \"https://your-webhook-url\"\r\n \"platform\": \"API\",\r\n \"created_from_ip\": \"183.83.53.41\",\r\n \"checkout_url\": \"https://api.choicepay.ca/payments/deb852445bd4b0fa6c4587f652174ab9/\",\r\n \"payoutProcess\": false\r\n}"},{"id":"ee484eed-a2b4-48c1-a801-7f19c57b4127","name":"Purchase - failure","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"url":"https://app.paybomb.tech/api/v1/purchases/{purchaseId}/"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"message\": \"Error Message\",\r\n \"code\": \"error_code\"\r\n}"}],"_postman_id":"e6dd61c4-6ca3-4cb3-bc16-76a6467d083e"}],"id":"fbcf6289-1ca0-4e35-9756-6ea0c5abb7a8","description":"

API Flow

The merchant initiates the purchase via the create purchase API and passing the appropriate payment method. If successful, they receive a checkout URL in the response JSON.
\n
Upon utilizing the checkout URL, the user will be presented with a screen where he will be shown a button to pay via Applepay.
\n
After clicking the button, the user will see all the cards stored in the Apple wallet and he can choose one of the cards to make the purchase.
\n
After a successful or failed payment by the end user, an appropriate webhook would be sent to the merchant. The user would also be redirected to the appropriate redirect URL.
\n

Get started

Paybomb’s Server-to-Server (S2S) integration for Google Pay allows merchants to process Google Pay transactions securely from their backend systems. In this model, merchants are responsible for generating the Google Pay payment token on their client application and sending it to their server, which then communicates with Paybomb APIs.

This integration uses DIRECT tokenization, where payment data is securely generated by Google Pay and passed to Paybomb for processing.

This integration is recommended for merchants who require:

Integration with Google Pay wallets
\n
Secure handling of tokenized payment data
\n
Flexibility in choosing PCI scope (encrypted vs decrypted flow)
\n

How it works

The Google Pay S2S payment flow follows a two-step process:

1. Generate Google Pay Token (Client-side)

The merchant integrates Google Pay SDK (Web/Android) to generate a payment token using DIRECT flow.

2. Submit Token via S2S

The merchant server sends the Google Pay token (encrypted or decrypted) to Paybomb via the /purchase API.

Supported Tokenization Type

Paybomb supports DIRECT flow only.

PAYMENT_GATEWAY flow is not supported yet.

Google Pay Processing Overview

Google Pay transactions are processed as card-not-present payments using tokenized card data (PAN/DPAN) along with a cryptogram provided by Google Pay.

These transactions go through:

Card network (Visa, Mastercard, etc.)
\n
Issuing bank authorization
\n
Risk and fraud checks
\n

Integration Options

Paybomb supports two integration modes:

1. Encrypted Token Flow (Recommended)

In this flow, the merchant sends the encrypted Google Pay token to Paybomb. Paybomb decrypts and processes the payment.

Key Characteristics

Merchant does not handle PAN
\n
Reduced PCI scope
\n
Recommended for most merchants
\n

PCI Impact

Merchants can significantly reduce PCI DSS scope since sensitive card data is handled by Paybomb.

2. Decrypted Token Flow

In this flow, the merchant decrypts the Google Pay token and sends decrypted token details to Paybomb.

Key Characteristics

PAN is available at merchant side
\n
Faster processing
\n
Full control over payment data
\n

PCI Impact

Merchants must be PCI DSS compliant (SAQ D) as they handle raw card data.

Before you begin

Ensure the following prerequisites are met:

You have received your API credentials from Paybomb.
\n
You have a valid Google Merchant ID
\n
You have integrated Google Pay SDK to generate tokens
\n
You have configured DIRECT tokenization in Google Pay
\n
Your server can make secure HTTPS requests
\n
You have a valid brand_id provided by Paybomb
\n

Additional Requirements (Encrypted Flow)

Generate EC key pair (P-256 / secp256r1)
\n
Register public key in Google Pay Console
\n
Share private key securely with Paybomb
\n

Additional Requirements (Decrypted Flow)

Implement token decryption using Google Tink library
\n
Ensure full PCI DSS compliance
\n

\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"22615511-937a-4447-b8cd-21ef278274d2"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"a9d0598c-6ad7-49e0-9351-457258c29cb1"}}],"_postman_id":"ffd8cc10-2208-44f4-bb0a-b2e30642c194"},{"name":"APIs","item":[{"name":"Purchases (Encrypted Flow)","id":"a0fa98c9-d48c-4808-9a6a-9bfc99b5eb2d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer Token"}],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"customerId\": \"NA\",\r\n \"email\": \"himanshu1@paybomb.tech\",\r\n \"full_name\": \"OpHM\",\r\n \"date_of_birth\": \"1800-01-01\",\r\n \"street_address\": \"SB-124\",\r\n \"country\": \"BR\",\r\n \"city\": \"DLJPR\",\r\n \"zip_code\": \"110001\",\r\n \"cc\": [],\r\n \"bcc\": [],\r\n \"stateCode\": \"DL\"\r\n },\r\n \"purchase\": {\r\n \"currency\": \"EUR\",\r\n \"products\": [\r\n {\r\n \"name\": \"e-commerce\",\r\n \"price\": \"10\"\r\n }\r\n ]\r\n },\r\n \"paymentMethod\": \"GOOGLEPAY\",\r\n \"brand_id\": \"f1764688-d991-481b-be63-9ee7f33dcd31\",\r\n \"success_redirect\": \"https://google.com/\",\r\n \"pending_redirect\": \"https://app.paybomb.tech\",\r\n \"failure_redirect\": \"https://facebook.com/\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\",\r\n \"extraParam\": {\r\n \"googlepay_param\": {\r\n \"google_merchant_id\": \"merchant:1234567890\",\r\n \"googlepay_encrypted_payload\": \"{\\\"signature\\\":\\\"MEUCIQC...\\\",\\\"intermediateSigningKey\\\":{...},\\\"protocolVersion\\\":\\\"ECv2\\\",\\\"signedMessage\\\":\\\"{...}\\\"}\"\r\n }\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/purchases/","description":"

To process a Google Pay transaction, a Purchase must first be created using the /purchases API. The Google Pay token must be included in the request under extraParam.googlepay_param.

To generate a Purchase, you are required to provide the Brand ID (in the request body) and API key (in the header) Both can be located in the Dashboard section of your merchant account login.

The request body structure is shown on the request body of the example request shown here.

The following (see table below) are the mandatory parameters that are required to create a purchase request.

Parameters in the request body:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Notes
client.full_name	Conditional. But Recommended to pass the complete name of the client. Atleast 2 words recommended.
client.email	Conditional. But Recommended to pass a correct email id.
paymentMethod	Conditional. Mandatory if you are not using Paybomb Cashier. Else Non Mandatory. Value: GOOGLEPAY
purchase.currency	Mandatory. ISO 4217 code for currency you want to send the transaction in. This should be 'BRL' for PIX.
purchase.products.name	Mandatory.
purchase.products.price	Mandatory. Price in decimal format upto 2 decimals. example 1: EUR 5 , should be sent as 5.00 example 2: USD 10 and 37 cents , should be sent as 10.37
brand_id	Mandatory. Obtain from Dashboard section of your merchant account login.
success_redirect	Mandatory. URL to send the user if the transactions is successful.
pending_redirect	Mandatory. URL to send the user if the transactions is in progress state.
failure_redirect	Mandatory URL to send the user if the transactions has failed.

Optional Parameters

expireInMin

merchantRef

The merchantRef parameter, although not mandatory, is strongly advised for merchants to specify. Its inclusion offers two significant advantages for the merchant:

Prevention of Duplicate Requests: When a merchantRef is utilized, it acts as a unique identifier. This means that if a second purchase request is made using the same merchantRef (reference number), the system will recognize it and prevent duplicate transactions from occurring. This prevents unintended or duplicate purchases.
\n
Facilitation of Transaction Retrieval: In situations where the response from the initial purchase request times out or the 'purchaseId' isn't received, having the merchantRef allows the merchant to retrieve detailed transaction information. This ensures they can track and access the specific purchase details related to that reference, even if the immediate response was not received.
\n

However, if the merchant does not specify the 'merchantRef' parameter, the platform will automatically assign and use an internal 'purchaseId' as a reference for that transaction.

paymentMethod

Flow Diagram:

","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"10a74d03-6fd9-44fa-855a-b85154a1da10","id":"10a74d03-6fd9-44fa-855a-b85154a1da10","name":"APIs","type":"folder"}},"urlObject":{"path":["purchases",""],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"709dd50d-22de-4962-9a3b-6e2f05de2980","name":"Purchase - success","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer Token"}],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"customerId\": \"NA\",\r\n \"email\": \"himanshu1@paybomb.tech\",\r\n \"full_name\": \"OpHM\",\r\n \"date_of_birth\": \"1800-01-01\",\r\n \"street_address\": \"SB-124\",\r\n \"country\": \"BR\",\r\n \"city\": \"DLJPR\",\r\n \"zip_code\": \"110001\",\r\n \"cc\": [],\r\n \"bcc\": [],\r\n \"stateCode\": \"DL\"\r\n },\r\n \"purchase\": {\r\n \"currency\": \"EUR\",\r\n \"products\": [\r\n {\r\n \"name\": \"e-commerce\",\r\n \"price\": \"10\"\r\n }\r\n ]\r\n },\r\n \"paymentMethod\": \"GOOGLEPAY\",\r\n \"brand_id\": \"f1764688-d991-481b-be63-9ee7f33dcd31\",\r\n \"success_redirect\": \"https://google.com/\",\r\n \"pending_redirect\": \"https://app.paybomb.tech\",\r\n \"failure_redirect\": \"https://facebook.com/\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\",\r\n \"extraParam\": {\r\n \"googlepay_param\": {\r\n \"google_merchant_id\": \"merchant:1234567890\",\r\n \"googlepay_encrypted_payload\": \"{\\\"signature\\\":\\\"MEUCIQC...\\\",\\\"intermediateSigningKey\\\":{...},\\\"protocolVersion\\\":\\\"ECv2\\\",\\\"signedMessage\\\":\\\"{...}\\\"}\" \r\n }\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/purchases"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"purchaseId\": \"69cce01f5bae56fd5547a993\",\r\n \"client\": {\r\n \"customerId\": \"NA\",\r\n \"email\": \"himanshu1@paybomb.tech\",\r\n \"full_name\": \"OpHM\",\r\n \"date_of_birth\": \"1800-01-01\",\r\n \"street_address\": \"SB-124\",\r\n \"country\": \"BR\",\r\n \"city\": \"DLJPR\",\r\n \"zip_code\": \"110001\",\r\n \"cc\": [],\r\n \"bcc\": [],\r\n \"stateCode\": \"DL\"\r\n },\r\n \"updated_on\": 1775034399,\r\n \"type\": \"purchase\",\r\n \"paymentMethod\": \"GOOGLEPAY\",\r\n \"amountUnit\": \"MAJOR\",\r\n \"errorMsg\": \"\",\r\n \"errorCode\": \"NA\",\r\n \"force_recurring\": false,\r\n \"created_on\": 1775034399,\r\n \"merchantRef\": \"69cce01f5bae56fd5547a993\",\r\n \"purchase\": {\r\n \"currency\": \"USD\",\r\n \"products\": [\r\n {\r\n \"name\": \"e-commerce\",\r\n \"quantity\": 1.0,\r\n \"price\": 10.0,\r\n \"discount\": 0,\r\n \"tax_percent\": \"0.00\"\r\n }\r\n ],\r\n \"total\": 10.0,\r\n \"requestAmount\": 10.0,\r\n \"language\": \"en\",\r\n \"notes\": \"\",\r\n \"debt\": 0,\r\n \"total_formatted\": 1.0,\r\n \"taxAmount\": 0.0,\r\n \"taxPercent\": 0.0,\r\n \"request_client_details\": [],\r\n \"email_message\": \"\"\r\n },\r\n \"issuer_details\": {\r\n \"website\": \"\",\r\n \"legal_street_address\": \"\",\r\n \"legal_country\": \"\",\r\n \"legal_city\": \"\",\r\n \"legal_zip_code\": \"\",\r\n \"bank_accounts\": [\r\n {}\r\n ],\r\n \"legal_name\": \"Omega Pixel\",\r\n \"brand_name\": \"Omega Pixel\",\r\n \"registration_number\": \"\",\r\n \"tax_number\": \"\"\r\n },\r\n \"transaction_data\": {\r\n \"payment_method\": \"\",\r\n \"flow\": \"payform\",\r\n \"extra\": {},\r\n \"country\": \"\",\r\n \"attempts\": []\r\n },\r\n \"status\": \"CREATED\",\r\n \"status_history\": [\r\n {\r\n \"status\": \"created\",\r\n \"timestamp\": 1775034399\r\n }\r\n ],\r\n \"is_test\": false,\r\n \"brand_id\": \"f1764688-d991-481b-be63-9ee7f33dcd31\",\r\n \"send_receipt\": false,\r\n \"is_recurring_token\": false,\r\n \"skip_capture\": false,\r\n \"reference_generated\": \"PS1032\",\r\n \"issued\": \"2026-04-01\",\r\n \"due\": 1775034399,\r\n \"refund_upto\": 0,\r\n \"cc_descriptor\": \"\",\r\n \"fraudScore\": \"NA\",\r\n \"trustScore\": \"NA\",\r\n \"extraFee\": \"0\",\r\n \"paidOn\": 0,\r\n \"receivedAmt\": 0.0,\r\n \"taxAmount\": 0.0,\r\n \"surcharge\": 0.0,\r\n \"surchargeType\": \"\",\r\n \"sessionId\": \"\",\r\n \"refund_availability\": \"NONE\",\r\n \"refundable_amount\": 0.0,\r\n \"success_redirect\": \"https://google.com/\",\r\n \"failure_redirect\": \"https://facebook.com/\",\r\n \"pending_redirect\": \"https://app.paybomb.tech\",\r\n \"cancel_redirect\": \"\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\",\r\n \"platform\": \"API\",\r\n \"created_from_ip\": \"103.80.161.238\",\r\n \"checkout_url\": \"https://api.choicepay.ca/payments/6b5a5977ac8e022facb31f3346f61ed0/\",\r\n \"direct_post_url\": \"https://api.choicepay.ca/api/v1/p/69cce01f5bae56fd5547a993/\",\r\n \"payoutProcess\": false\r\n}"},{"id":"9b60cc04-bfa7-4449-8125-eae2a3e69adc","name":"Purchase - failure","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer Token"}],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"customerId\": \"NA\",\r\n \"email\": \"himanshu1@paybomb.tech\",\r\n \"full_name\": \"OpHM\",\r\n \"date_of_birth\": \"1800-01-01\",\r\n \"street_address\": \"SB-124\",\r\n \"country\": \"BR\",\r\n \"city\": \"DLJPR\",\r\n \"zip_code\": \"110001\",\r\n \"cc\": [],\r\n \"bcc\": [],\r\n \"stateCode\": \"DL\"\r\n },\r\n \"purchase\": {\r\n \"currency\": \"EUR\",\r\n \"products\": [\r\n {\r\n \"name\": \"e-commerce\",\r\n \"price\": \"10\"\r\n }\r\n ]\r\n },\r\n \"paymentMethod\": \"GOOGLEPAY\",\r\n \"brand_id\": \"f1764688-d991-481b-be63-9ee7f33dcd31\",\r\n \"success_redirect\": \"https://google.com/\",\r\n \"pending_redirect\": \"https://app.paybomb.tech\",\r\n \"failure_redirect\": \"https://facebook.com/\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\",\r\n \"extraParam\": {\r\n \"googlepay_param\": {\r\n \"google_merchant_id\": \"merchant:1234567890\",\r\n \"googlepay_encrypted_payload\": \"{\\\"signature\\\":\\\"MEUCIQC...\\\",\\\"intermediateSigningKey\\\":{...},\\\"protocolVersion\\\":\\\"ECv2\\\",\\\"signedMessage\\\":\\\"{...}\\\"}\"\r\n }\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/purchases"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"message\": \"Error Message\",\r\n \"code\": \"error_code\"\r\n}"}],"_postman_id":"a0fa98c9-d48c-4808-9a6a-9bfc99b5eb2d"},{"name":"Purchases (Decrypted Flow)","id":"b6f0a2f3-f04d-4a0d-8a37-c92a79b8b250","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer Token"}],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"customerId\": \"NA\",\r\n \"email\": \"himanshu1@paybomb.tech\",\r\n \"full_name\": \"OpHM\",\r\n \"date_of_birth\": \"1800-01-01\",\r\n \"street_address\": \"SB-124\",\r\n \"country\": \"BR\",\r\n \"city\": \"DLJPR\",\r\n \"zip_code\": \"110001\",\r\n \"cc\": [],\r\n \"bcc\": [],\r\n \"stateCode\": \"DL\"\r\n },\r\n \"purchase\": {\r\n \"currency\": \"EUR\",\r\n \"products\": [\r\n {\r\n \"name\": \"e-commerce\",\r\n \"price\": \"10\"\r\n }\r\n ]\r\n },\r\n \"paymentMethod\": \"GOOGLEPAY\",\r\n \"brand_id\": \"f1764688-d991-481b-be63-9ee7f33dcd31\",\r\n \"success_redirect\": \"https://google.com/\",\r\n \"pending_redirect\": \"https://app.paybomb.tech\",\r\n \"failure_redirect\": \"https://facebook.com/\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\",\r\n \"extraParam\": {\r\n \"googlepay_param\": {\r\n \"google_merchant_id\": \"merchant:1234567890\",\r\n \"googlepay_decrypted_payload\": {\r\n \"messageExpiration\": \"1735689600000\",\r\n \"messageId\": \"AH2EjtfkYz...\",\r\n \"paymentMethod\": \"CARD\",\r\n \"paymentMethodDetails\": {\r\n \"pan\": \"4111111111111111\",\r\n \"expirationMonth\": 12,\r\n \"expirationYear\": 2027,\r\n \"authMethod\": \"CRYPTOGRAM_3DS\",\r\n \"cryptogram\": \"AgAAAAAABk4D...\",\r\n \"eciIndicator\": \"05\"\r\n },\r\n \"gatewayMerchantId\": \"your_gateway_merchant_id\"\r\n }\r\n }\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/purchases/","description":"

To process a Google Pay transaction, a Purchase must first be created using the /purchases API. The Google Pay token must be included in the request under extraParam.googlepay_param.

To generate a Purchase, you are required to provide the Brand ID (in the request body) and API key (in the header) Both can be located in the Dashboard section of your merchant account login.

The request body structure is shown on the request body of the example request shown here.

The following (see table below) are the mandatory parameters that are required to create a purchase request.

Parameters in the request body:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Notes
client.full_name	Conditional. But Recommended to pass the complete name of the client. Atleast 2 words recommended.
client.email	Conditional. But Recommended to pass a correct email id.
paymentMethod	Conditional. Mandatory if you are not using Paybomb Cashier. Else Non Mandatory. Value: GOOGLEPAY
purchase.currency	Mandatory. ISO 4217 code for currency you want to send the transaction in. This should be 'BRL' for PIX.
purchase.products.name	Mandatory.
purchase.products.price	Mandatory. Price in decimal format upto 2 decimals. example 1: EUR 5 , should be sent as 5.00 example 2: USD 10 and 37 cents , should be sent as 10.37
brand_id	Mandatory. Obtain from Dashboard section of your merchant account login.
success_redirect	Mandatory. URL to send the user if the transactions is successful.
pending_redirect	Mandatory. URL to send the user if the transactions is in progress state.
failure_redirect	Mandatory URL to send the user if the transactions has failed.

Optional Parameters

expireInMin

merchantRef

The merchantRef parameter, although not mandatory, is strongly advised for merchants to specify. Its inclusion offers two significant advantages for the merchant:

Prevention of Duplicate Requests: When a merchantRef is utilized, it acts as a unique identifier. This means that if a second purchase request is made using the same merchantRef (reference number), the system will recognize it and prevent duplicate transactions from occurring. This prevents unintended or duplicate purchases.
\n
Facilitation of Transaction Retrieval: In situations where the response from the initial purchase request times out or the 'purchaseId' isn't received, having the merchantRef allows the merchant to retrieve detailed transaction information. This ensures they can track and access the specific purchase details related to that reference, even if the immediate response was not received.
\n

However, if the merchant does not specify the 'merchantRef' parameter, the platform will automatically assign and use an internal 'purchaseId' as a reference for that transaction.

paymentMethod

Flow Diagram:

","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"10a74d03-6fd9-44fa-855a-b85154a1da10","id":"10a74d03-6fd9-44fa-855a-b85154a1da10","name":"APIs","type":"folder"}},"urlObject":{"path":["purchases",""],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"d35dd17a-4ee5-4fa7-8c45-130f462a6dca","name":"Purchase - success","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer Token"}],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"customerId\": \"NA\",\r\n \"email\": \"himanshu1@paybomb.tech\",\r\n \"full_name\": \"OpHM\",\r\n \"date_of_birth\": \"1800-01-01\",\r\n \"street_address\": \"SB-124\",\r\n \"country\": \"BR\",\r\n \"city\": \"DLJPR\",\r\n \"zip_code\": \"110001\",\r\n \"cc\": [],\r\n \"bcc\": [],\r\n \"stateCode\": \"DL\"\r\n },\r\n \"purchase\": {\r\n \"currency\": \"EUR\",\r\n \"products\": [\r\n {\r\n \"name\": \"e-commerce\",\r\n \"price\": \"10\"\r\n }\r\n ]\r\n },\r\n \"paymentMethod\": \"GOOGLEPAY\",\r\n \"brand_id\": \"f1764688-d991-481b-be63-9ee7f33dcd31\",\r\n \"success_redirect\": \"https://google.com/\",\r\n \"pending_redirect\": \"https://app.paybomb.tech\",\r\n \"failure_redirect\": \"https://facebook.com/\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\",\r\n \"extraParam\": {\r\n \"googlepay_param\": {\r\n \"google_merchant_id\": \"merchant:1234567890\",\r\n \"googlepay_decrypted_payload\": {\r\n \"messageExpiration\": \"1735689600000\",\r\n \"messageId\": \"AH2EjtfkYz...\",\r\n \"paymentMethod\": \"CARD\",\r\n \"paymentMethodDetails\": {\r\n \"pan\": \"4111111111111111\",\r\n \"expirationMonth\": 12,\r\n \"expirationYear\": 2027,\r\n \"authMethod\": \"CRYPTOGRAM_3DS\",\r\n \"cryptogram\": \"AgAAAAAABk4D...\",\r\n \"eciIndicator\": \"05\"\r\n },\r\n \"gatewayMerchantId\": \"your_gateway_merchant_id\"\r\n }\r\n }\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/purchases"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"purchaseId\": \"69cce01f5bae56fd5547a993\",\r\n \"client\": {\r\n \"customerId\": \"NA\",\r\n \"email\": \"himanshu1@paybomb.tech\",\r\n \"full_name\": \"OpHM\",\r\n \"date_of_birth\": \"1800-01-01\",\r\n \"street_address\": \"SB-124\",\r\n \"country\": \"BR\",\r\n \"city\": \"DLJPR\",\r\n \"zip_code\": \"110001\",\r\n \"cc\": [],\r\n \"bcc\": [],\r\n \"stateCode\": \"DL\"\r\n },\r\n \"updated_on\": 1775034399,\r\n \"type\": \"purchase\",\r\n \"paymentMethod\": \"GOOGLEPAY\",\r\n \"amountUnit\": \"MAJOR\",\r\n \"errorMsg\": \"\",\r\n \"errorCode\": \"NA\",\r\n \"force_recurring\": false,\r\n \"created_on\": 1775034399,\r\n \"merchantRef\": \"69cce01f5bae56fd5547a993\",\r\n \"purchase\": {\r\n \"currency\": \"USD\",\r\n \"products\": [\r\n {\r\n \"name\": \"e-commerce\",\r\n \"quantity\": 1.0,\r\n \"price\": 10.0,\r\n \"discount\": 0,\r\n \"tax_percent\": \"0.00\"\r\n }\r\n ],\r\n \"total\": 10.0,\r\n \"requestAmount\": 10.0,\r\n \"language\": \"en\",\r\n \"notes\": \"\",\r\n \"debt\": 0,\r\n \"total_formatted\": 1.0,\r\n \"taxAmount\": 0.0,\r\n \"taxPercent\": 0.0,\r\n \"request_client_details\": [],\r\n \"email_message\": \"\"\r\n },\r\n \"issuer_details\": {\r\n \"website\": \"\",\r\n \"legal_street_address\": \"\",\r\n \"legal_country\": \"\",\r\n \"legal_city\": \"\",\r\n \"legal_zip_code\": \"\",\r\n \"bank_accounts\": [\r\n {}\r\n ],\r\n \"legal_name\": \"Omega Pixel\",\r\n \"brand_name\": \"Omega Pixel\",\r\n \"registration_number\": \"\",\r\n \"tax_number\": \"\"\r\n },\r\n \"transaction_data\": {\r\n \"payment_method\": \"\",\r\n \"flow\": \"payform\",\r\n \"extra\": {},\r\n \"country\": \"\",\r\n \"attempts\": []\r\n },\r\n \"status\": \"CREATED\",\r\n \"status_history\": [\r\n {\r\n \"status\": \"created\",\r\n \"timestamp\": 1775034399\r\n }\r\n ],\r\n \"is_test\": false,\r\n \"brand_id\": \"f1764688-d991-481b-be63-9ee7f33dcd31\",\r\n \"send_receipt\": false,\r\n \"is_recurring_token\": false,\r\n \"skip_capture\": false,\r\n \"reference_generated\": \"PS1032\",\r\n \"issued\": \"2026-04-01\",\r\n \"due\": 1775034399,\r\n \"refund_upto\": 0,\r\n \"cc_descriptor\": \"\",\r\n \"fraudScore\": \"NA\",\r\n \"trustScore\": \"NA\",\r\n \"extraFee\": \"0\",\r\n \"paidOn\": 0,\r\n \"receivedAmt\": 0.0,\r\n \"taxAmount\": 0.0,\r\n \"surcharge\": 0.0,\r\n \"surchargeType\": \"\",\r\n \"sessionId\": \"\",\r\n \"refund_availability\": \"NONE\",\r\n \"refundable_amount\": 0.0,\r\n \"success_redirect\": \"https://google.com/\",\r\n \"failure_redirect\": \"https://facebook.com/\",\r\n \"pending_redirect\": \"https://app.paybomb.tech\",\r\n \"cancel_redirect\": \"\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\",\r\n \"platform\": \"API\",\r\n \"created_from_ip\": \"103.80.161.238\",\r\n \"checkout_url\": \"https://api.choicepay.ca/payments/6b5a5977ac8e022facb31f3346f61ed0/\",\r\n \"direct_post_url\": \"https://api.choicepay.ca/api/v1/p/69cce01f5bae56fd5547a993/\",\r\n \"payoutProcess\": false\r\n}"},{"id":"43d7ddb7-81f9-4803-8818-cf7a227277d3","name":"Purchase - failure","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer Token"}],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"customerId\": \"NA\",\r\n \"email\": \"himanshu1@paybomb.tech\",\r\n \"full_name\": \"OpHM\",\r\n \"date_of_birth\": \"1800-01-01\",\r\n \"street_address\": \"SB-124\",\r\n \"country\": \"BR\",\r\n \"city\": \"DLJPR\",\r\n \"zip_code\": \"110001\",\r\n \"cc\": [],\r\n \"bcc\": [],\r\n \"stateCode\": \"DL\"\r\n },\r\n \"purchase\": {\r\n \"currency\": \"EUR\",\r\n \"products\": [\r\n {\r\n \"name\": \"e-commerce\",\r\n \"price\": \"10\"\r\n }\r\n ]\r\n },\r\n \"paymentMethod\": \"GOOGLEPAY\",\r\n \"brand_id\": \"f1764688-d991-481b-be63-9ee7f33dcd31\",\r\n \"success_redirect\": \"https://google.com/\",\r\n \"pending_redirect\": \"https://app.paybomb.tech\",\r\n \"failure_redirect\": \"https://facebook.com/\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\",\r\n \"extraParam\": {\r\n \"googlepay_param\": {\r\n \"google_merchant_id\": \"merchant:1234567890\",\r\n \"googlepay_decrypted_payload\": {\r\n \"messageExpiration\": \"1735689600000\",\r\n \"messageId\": \"AH2EjtfkYz...\",\r\n \"paymentMethod\": \"CARD\",\r\n \"paymentMethodDetails\": {\r\n \"pan\": \"4111111111111111\",\r\n \"expirationMonth\": 12,\r\n \"expirationYear\": 2027,\r\n \"authMethod\": \"CRYPTOGRAM_3DS\",\r\n \"cryptogram\": \"AgAAAAAABk4D...\",\r\n \"eciIndicator\": \"05\"\r\n },\r\n \"gatewayMerchantId\": \"your_gateway_merchant_id\"\r\n }\r\n }\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/purchases"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"message\": \"Error Message\",\r\n \"code\": \"error_code\"\r\n}"}],"_postman_id":"b6f0a2f3-f04d-4a0d-8a37-c92a79b8b250"},{"name":"Get Status","id":"7394ccf0-c709-4e4a-8936-d43545aab895","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"url":"https://app.paybomb.tech/api/v1/purchases/{purchaseId}/","description":"

This API tells you about all the details of a purchase (PayIn), including its history

Mandatory

you need to pass the PurchaseID in the API URL

Possible Value of Status

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Notes
paid	Transaction Successful
payment_in_process	Payment is under Processing
expired	Purchase has Expired.
error	Transaction has Failed.

Response Examples

In the response examples you can see instances of both Paid and Error Status purchases.

Error Details

If there are any issues on the Purchase you can get more details from the transaction_data.attempts.error attribute of the response object

Errors

If there are any errors then it'll be in the format of :

{\n    \"message\": \"descriptive error message\",\n    \"code\": \"error_code\"\n}\n\n

Please see the Status Code section for further details.

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"10a74d03-6fd9-44fa-855a-b85154a1da10","id":"10a74d03-6fd9-44fa-855a-b85154a1da10","name":"APIs","type":"folder"}},"urlObject":{"path":["purchases","{purchaseId}",""],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"ff790ecb-5ce6-4b09-8e1b-35a1c268b106","name":"Purchase - success","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer Token"}],"url":"https://app.paybomb.tech/api/v1/purchases/{purchaseId}/"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"purchaseId\": \"69cce01f5bae56fd5547a993\",\r\n \"client\": {\r\n \"customerId\": \"NA\",\r\n \"email\": \"himanshu1@paybomb.tech\",\r\n \"full_name\": \"OpHM\",\r\n \"date_of_birth\": \"1800-01-01\",\r\n \"street_address\": \"SB-124\",\r\n \"country\": \"BR\",\r\n \"city\": \"DLJPR\",\r\n \"zip_code\": \"110001\",\r\n \"cc\": [],\r\n \"bcc\": [],\r\n \"stateCode\": \"DL\"\r\n },\r\n \"updated_on\": 1775034399,\r\n \"type\": \"purchase\",\r\n \"paymentMethod\": \"GOOGLEPAY\",\r\n \"amountUnit\": \"MAJOR\",\r\n \"errorMsg\": \"\",\r\n \"errorCode\": \"NA\",\r\n \"force_recurring\": false,\r\n \"created_on\": 1775034399,\r\n \"merchantRef\": \"69cce01f5bae56fd5547a993\",\r\n \"purchase\": {\r\n \"currency\": \"USD\",\r\n \"products\": [\r\n {\r\n \"name\": \"e-commerce\",\r\n \"quantity\": 1.0,\r\n \"price\": 10.0,\r\n \"discount\": 0,\r\n \"tax_percent\": \"0.00\"\r\n }\r\n ],\r\n \"total\": 10.0,\r\n \"requestAmount\": 10.0,\r\n \"language\": \"en\",\r\n \"notes\": \"\",\r\n \"debt\": 0,\r\n \"total_formatted\": 1.0,\r\n \"taxAmount\": 0.0,\r\n \"taxPercent\": 0.0,\r\n \"request_client_details\": [],\r\n \"email_message\": \"\"\r\n },\r\n \"issuer_details\": {\r\n \"website\": \"\",\r\n \"legal_street_address\": \"\",\r\n \"legal_country\": \"\",\r\n \"legal_city\": \"\",\r\n \"legal_zip_code\": \"\",\r\n \"bank_accounts\": [\r\n {}\r\n ],\r\n \"legal_name\": \"Omega Pixel\",\r\n \"brand_name\": \"Omega Pixel\",\r\n \"registration_number\": \"\",\r\n \"tax_number\": \"\"\r\n },\r\n \"transaction_data\": {\r\n \"payment_method\": \"\",\r\n \"flow\": \"payform\",\r\n \"extra\": {},\r\n \"country\": \"\",\r\n \"attempts\": []\r\n },\r\n \"status\": \"CREATED\",\r\n \"status_history\": [\r\n {\r\n \"status\": \"created\",\r\n \"timestamp\": 1775034399\r\n }\r\n ],\r\n \"is_test\": false,\r\n \"brand_id\": \"f1764688-d991-481b-be63-9ee7f33dcd31\",\r\n \"send_receipt\": false,\r\n \"is_recurring_token\": false,\r\n \"skip_capture\": false,\r\n \"reference_generated\": \"PS1032\",\r\n \"issued\": \"2026-04-01\",\r\n \"due\": 1775034399,\r\n \"refund_upto\": 0,\r\n \"cc_descriptor\": \"\",\r\n \"fraudScore\": \"NA\",\r\n \"trustScore\": \"NA\",\r\n \"extraFee\": \"0\",\r\n \"paidOn\": 0,\r\n \"receivedAmt\": 0.0,\r\n \"taxAmount\": 0.0,\r\n \"surcharge\": 0.0,\r\n \"surchargeType\": \"\",\r\n \"sessionId\": \"\",\r\n \"refund_availability\": \"NONE\",\r\n \"refundable_amount\": 0.0,\r\n \"success_redirect\": \"https://google.com/\",\r\n \"failure_redirect\": \"https://facebook.com/\",\r\n \"pending_redirect\": \"https://app.paybomb.tech\",\r\n \"cancel_redirect\": \"\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\",\r\n \"platform\": \"API\",\r\n \"created_from_ip\": \"103.80.161.238\",\r\n \"checkout_url\": \"https://api.choicepay.ca/payments/6b5a5977ac8e022facb31f3346f61ed0/\",\r\n \"direct_post_url\": \"https://api.choicepay.ca/api/v1/p/69cce01f5bae56fd5547a993/\",\r\n \"payoutProcess\": false\r\n}"},{"id":"f39db69b-b3d7-46aa-8e82-f3675be063d0","name":"Purchase - failure","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"url":"https://app.paybomb.tech/api/v1/purchases/{purchaseId}/"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"message\": \"Error Message\",\r\n \"code\": \"error_code\"\r\n}"}],"_postman_id":"7394ccf0-c709-4e4a-8936-d43545aab895"}],"id":"10a74d03-6fd9-44fa-855a-b85154a1da10","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"f7b7015d-25c5-4b0e-8d9c-e6344b9a8b89"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"68cabbf7-255d-4e6a-8439-caae758e5bfe"}}],"_postman_id":"10a74d03-6fd9-44fa-855a-b85154a1da10","description":""}],"id":"de62fb1c-d00b-4fb8-ad45-931ff1045a45","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"912fd6dd-9379-432e-bd83-45e3741e045d"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"d1292fbb-1e90-4b10-b78c-c05083be33b2"}}],"_postman_id":"de62fb1c-d00b-4fb8-ad45-931ff1045a45","description":""},{"name":"🌎 Apple Pay (Seamless)","item":[{"name":"Concepts","item":[],"id":"78613d1e-3429-4750-9b9e-6d6a2c4343f9","description":"

Get started

Paybomb’s Server-to-Server (S2S) integration for Apple Pay allows merchants to process Apple Pay transactions securely from their backend systems. In this model, merchants are responsible for generating the Apple Pay payment token on their client application and sending it to their server, which then communicates with Paybomb APIs.

This integration uses DIRECT tokenization, where payment data is securely generated by Apple Pay and passed to Paybomb for processing.

This integration is recommended for merchants who require:

Integration with Apple Pay wallets
\n
Secure handling of tokenized payment data
\n
Flexibility in choosing PCI scope (encrypted vs decrypted flow)
\n

How it works

The Apple Pay S2S payment flow follows a two-step process:

1. Generate Apple Pay Token (Client-side)

The merchant integrates Apple Pay SDK (Web/Android) to generate a payment token using DIRECT flow.

2. Submit Token via S2S

The merchant server sends the Apple Pay token (encrypted or decrypted) to Paybomb via the /purchase API.

Apple Pay Processing Overview

Apple Pay transactions are processed as card-not-present payments using:

Tokenized card data (DPAN)
\n
Cryptogram generated by Apple
\n
Device-based authentication (Face ID / Touch ID / Passcode)
\n

These transactions go through:

Card network (Visa, Mastercard, Amex, etc.)
\n
Issuing bank authorization
\n
Risk and fraud checks
\n

Integration Options

Paybomb supports two integration modes:

1. Encrypted Token Flow (Recommended)

In this flow, the merchant sends the encrypted Apple Pay token to Paybomb. Paybomb decrypts and processes the payment.

Key Characteristics

Merchant does not handle PAN
\n
Reduced PCI scope
\n
Recommended for most merchants
\n

PCI Impact

Merchants can significantly reduce PCI DSS scope since sensitive card data is handled by Paybomb.

2. Decrypted Token Flow

In this flow, the merchant decrypts the Apple Pay token and sends card details to Paybomb.

Key Characteristics

PAN/DPAN available at merchant side
\n
Full control over payment data
\n

PCI Impact

Merchants must be PCI DSS compliant (SAQ D) as they handle raw card data.

Before you begin

Ensure the following prerequisites are met:

You have received your API credentials from Paybomb
\n
You have an Apple Merchant ID
\n
You have configured Apple Pay on your domain/app
\n
Your server can make secure HTTPS requests
\n
You have a valid brand_id provided by Paybomb
\n

Additional Requirements (Encrypted Flow)

Configure Apple Pay certificates (Payment Processing Certificate)
\n
Share certificate details securely with Paybomb (if required)
\n

Additional Requirements (Decrypted Flow)

Implement Apple Pay token decryption
\n
Use Apple’s Payment Processing certificate and private key
\n
Ensure full PCI DSS compliance
\n

\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"c931580a-3ccb-4810-9a49-6ac90843cad1"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"6cd62f15-6e03-4f21-8808-78e201bb14e1"}}],"_postman_id":"78613d1e-3429-4750-9b9e-6d6a2c4343f9"},{"name":"APIs","item":[{"name":"Purchases (Encrypted Flow)","id":"89c7d10d-6ddd-4cca-bf99-0b08f605f6c6","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer Token"}],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"email\": \"customer@example.com\"\r\n },\r\n \"purchase\": {\r\n \"currency\": \"USD\",\r\n \"products\": [\r\n {\r\n \"name\": \"Product\",\r\n \"price\": \"10.00\"\r\n }\r\n ]\r\n },\r\n \"paymentMethod\": \"APPLEPAY\",\r\n \"brand_id\": \"your_brand_id\",\r\n \"success_redirect\": \"https://success.com\",\r\n \"pending_redirect\": \"https://pending.com\",\r\n \"failure_redirect\": \"https://failure.com\",\r\n \"extraParam\": {\r\n \"applepay_param\": {\r\n \"applepay_token\": {\r\n \"version\": \"EC_v1\",\r\n \"data\": \"...\",\r\n \"signature\": \"...\",\r\n \"header\": {\r\n \"ephemeralPublicKey\": \"...\",\r\n \"publicKeyHash\": \"...\",\r\n \"transactionId\": \"...\"\r\n }\r\n }\r\n }\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/purchases/","description":"

To process an Apple Pay transaction, a Purchase must be created using the /purchases API. The Apple Pay token must be included under extraParam.applepay_param.

To generate a Purchase, you are required to provide the Brand ID (in the request body) and API key (in the header) Both can be located in the Dashboard section of your merchant account login.

The request body structure is shown on the request body of the example request shown here.

The following (see table below) are the mandatory parameters that are required to create a purchase request.

Parameters in the request body:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Notes
client.full_name	Conditional. But Recommended to pass the complete name of the client. Atleast 2 words recommended.
client.email	Conditional. But Recommended to pass a correct email id.
paymentMethod	Conditional. Mandatory if you are not using Paybomb Cashier. Else Non Mandatory. Value: APPLEPAY
purchase.currency	Mandatory. ISO 4217 code for currency you want to send the transaction in. This should be 'BRL' for PIX.
purchase.products.name	Mandatory.
purchase.products.price	Mandatory. Price in decimal format upto 2 decimals. example 1: EUR 5 , should be sent as 5.00 example 2: USD 10 and 37 cents , should be sent as 10.37
brand_id	Mandatory. Obtain from Dashboard section of your merchant account login.
success_redirect	Mandatory. URL to send the user if the transactions is successful.
pending_redirect	Mandatory. URL to send the user if the transactions is in progress state.
failure_redirect	Mandatory URL to send the user if the transactions has failed.

Optional Parameters

expireInMin

merchantRef

The merchantRef parameter, although not mandatory, is strongly advised for merchants to specify. Its inclusion offers two significant advantages for the merchant:

Prevention of Duplicate Requests: When a merchantRef is utilized, it acts as a unique identifier. This means that if a second purchase request is made using the same merchantRef (reference number), the system will recognize it and prevent duplicate transactions from occurring. This prevents unintended or duplicate purchases.
\n
Facilitation of Transaction Retrieval: In situations where the response from the initial purchase request times out or the 'purchaseId' isn't received, having the merchantRef allows the merchant to retrieve detailed transaction information. This ensures they can track and access the specific purchase details related to that reference, even if the immediate response was not received.
\n

However, if the merchant does not specify the 'merchantRef' parameter, the platform will automatically assign and use an internal 'purchaseId' as a reference for that transaction.

paymentMethod

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"d8f27861-65fd-4f57-8c8d-92d00fa7558e","id":"d8f27861-65fd-4f57-8c8d-92d00fa7558e","name":"APIs","type":"folder"}},"urlObject":{"path":["purchases",""],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"4ec1b38c-183e-45f7-b835-d137701f6ef6","name":"Purchase - success","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer Token"}],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"email\": \"customer@example.com\"\r\n },\r\n \"purchase\": {\r\n \"currency\": \"USD\",\r\n \"products\": [\r\n {\r\n \"name\": \"Product\",\r\n \"price\": \"10.00\"\r\n }\r\n ]\r\n },\r\n \"paymentMethod\": \"APPLEPAY\",\r\n \"brand_id\": \"your_brand_id\",\r\n \"success_redirect\": \"https://success.com\",\r\n \"pending_redirect\": \"https://pending.com\",\r\n \"failure_redirect\": \"https://failure.com\",\r\n \"extraParam\": {\r\n \"applepay_param\": {\r\n \"applepay_token\": {\r\n \"version\": \"EC_v1\",\r\n \"data\": \"...\",\r\n \"signature\": \"...\",\r\n \"header\": {\r\n \"ephemeralPublicKey\": \"...\",\r\n \"publicKeyHash\": \"...\",\r\n \"transactionId\": \"...\"\r\n }\r\n }\r\n }\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/purchases"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"purchaseId\": \"69cce01f5bae56fd5547a993\",\r\n \"client\": {\r\n \"customerId\": \"NA\",\r\n \"email\": \"himanshu1@paybomb.tech\",\r\n \"full_name\": \"OpHM\",\r\n \"date_of_birth\": \"1800-01-01\",\r\n \"street_address\": \"SB-124\",\r\n \"country\": \"BR\",\r\n \"city\": \"DLJPR\",\r\n \"zip_code\": \"110001\",\r\n \"cc\": [],\r\n \"bcc\": [],\r\n \"stateCode\": \"DL\"\r\n },\r\n \"updated_on\": 1775034399,\r\n \"type\": \"purchase\",\r\n \"paymentMethod\": \"APPLEPAY\",\r\n \"amountUnit\": \"MAJOR\",\r\n \"errorMsg\": \"\",\r\n \"errorCode\": \"NA\",\r\n \"force_recurring\": false,\r\n \"created_on\": 1775034399,\r\n \"merchantRef\": \"69cce01f5bae56fd5547a993\",\r\n \"purchase\": {\r\n \"currency\": \"USD\",\r\n \"products\": [\r\n {\r\n \"name\": \"e-commerce\",\r\n \"quantity\": 1.0,\r\n \"price\": 10.0,\r\n \"discount\": 0,\r\n \"tax_percent\": \"0.00\"\r\n }\r\n ],\r\n \"total\": 10.0,\r\n \"requestAmount\": 10.0,\r\n \"language\": \"en\",\r\n \"notes\": \"\",\r\n \"debt\": 0,\r\n \"total_formatted\": 1.0,\r\n \"taxAmount\": 0.0,\r\n \"taxPercent\": 0.0,\r\n \"request_client_details\": [],\r\n \"email_message\": \"\"\r\n },\r\n \"issuer_details\": {\r\n \"website\": \"\",\r\n \"legal_street_address\": \"\",\r\n \"legal_country\": \"\",\r\n \"legal_city\": \"\",\r\n \"legal_zip_code\": \"\",\r\n \"bank_accounts\": [\r\n {}\r\n ],\r\n \"legal_name\": \"Omega Pixel\",\r\n \"brand_name\": \"Omega Pixel\",\r\n \"registration_number\": \"\",\r\n \"tax_number\": \"\"\r\n },\r\n \"transaction_data\": {\r\n \"payment_method\": \"\",\r\n \"flow\": \"payform\",\r\n \"extra\": {},\r\n \"country\": \"\",\r\n \"attempts\": []\r\n },\r\n \"status\": \"CREATED\",\r\n \"status_history\": [\r\n {\r\n \"status\": \"created\",\r\n \"timestamp\": 1775034399\r\n }\r\n ],\r\n \"is_test\": false,\r\n \"brand_id\": \"f1764688-d991-481b-be63-9ee7f33dcd31\",\r\n \"send_receipt\": false,\r\n \"is_recurring_token\": false,\r\n \"skip_capture\": false,\r\n \"reference_generated\": \"PS1032\",\r\n \"issued\": \"2026-04-01\",\r\n \"due\": 1775034399,\r\n \"refund_upto\": 0,\r\n \"cc_descriptor\": \"\",\r\n \"fraudScore\": \"NA\",\r\n \"trustScore\": \"NA\",\r\n \"extraFee\": \"0\",\r\n \"paidOn\": 0,\r\n \"receivedAmt\": 0.0,\r\n \"taxAmount\": 0.0,\r\n \"surcharge\": 0.0,\r\n \"surchargeType\": \"\",\r\n \"sessionId\": \"\",\r\n \"refund_availability\": \"NONE\",\r\n \"refundable_amount\": 0.0,\r\n \"success_redirect\": \"https://google.com/\",\r\n \"failure_redirect\": \"https://facebook.com/\",\r\n \"pending_redirect\": \"https://app.paybomb.tech\",\r\n \"cancel_redirect\": \"\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\",\r\n \"platform\": \"API\",\r\n \"created_from_ip\": \"103.80.161.238\",\r\n \"checkout_url\": \"https://api.choicepay.ca/payments/6b5a5977ac8e022facb31f3346f61ed0/\",\r\n \"direct_post_url\": \"https://api.choicepay.ca/api/v1/p/69cce01f5bae56fd5547a993/\",\r\n \"payoutProcess\": false\r\n}"},{"id":"6716ccae-8a7d-4d73-8deb-449b32d20f73","name":"Purchase - failure","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer Token"}],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"email\": \"customer@example.com\"\r\n },\r\n \"purchase\": {\r\n \"currency\": \"USD\",\r\n \"products\": [\r\n {\r\n \"name\": \"Product\",\r\n \"price\": \"10.00\"\r\n }\r\n ]\r\n },\r\n \"paymentMethod\": \"APPLEPAY\",\r\n \"brand_id\": \"your_brand_id\",\r\n \"success_redirect\": \"https://success.com\",\r\n \"pending_redirect\": \"https://pending.com\",\r\n \"failure_redirect\": \"https://failure.com\",\r\n \"extraParam\": {\r\n \"applepay_param\": {\r\n \"applepay_token\": {\r\n \"version\": \"EC_v1\",\r\n \"data\": \"...\",\r\n \"signature\": \"...\",\r\n \"header\": {\r\n \"ephemeralPublicKey\": \"...\",\r\n \"publicKeyHash\": \"...\",\r\n \"transactionId\": \"...\"\r\n }\r\n }\r\n }\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/purchases"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"message\": \"Error Message\",\r\n \"code\": \"error_code\"\r\n}"}],"_postman_id":"89c7d10d-6ddd-4cca-bf99-0b08f605f6c6"},{"name":"Purchases (Decrypted Flow)","id":"e53e191a-cc48-47a4-9125-bc42c6251680","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer Token"}],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"email\": \"customer@example.com\"\r\n },\r\n \"purchase\": {\r\n \"currency\": \"USD\",\r\n \"products\": [\r\n {\r\n \"name\": \"Product\",\r\n \"price\": \"10.00\"\r\n }\r\n ]\r\n },\r\n \"paymentMethod\": \"APPLEPAY\",\r\n \"brand_id\": \"your_brand_id\",\r\n \"success_redirect\": \"https://success.com\",\r\n \"pending_redirect\": \"https://pending.com\",\r\n \"failure_redirect\": \"https://failure.com\",\r\n \"extraParam\": {\r\n \"applepay_param\": {\r\n \"applepay_decrypted_payload\": {\r\n \"applicationPrimaryAccountNumber\": \"4111111111111111\",\r\n \"applicationExpirationDate\": \"2712\",\r\n \"currencyCode\": \"840\",\r\n \"transactionAmount\": 1000,\r\n \"deviceManufacturerIdentifier\": \"040010030273\",\r\n \"paymentDataType\": \"3DSecure\",\r\n \"paymentData\": {\r\n \"onlinePaymentCryptogram\": \"AgAAAAAABk4D...\",\r\n \"eciIndicator\": \"05\"\r\n }\r\n }\r\n }\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/purchases/","description":"

To process an Apple Pay transaction, a Purchase must be created using the /purchases API. The Apple Pay token must be included under extraParam.applepay_param.

To generate a Purchase, you are required to provide the Brand ID (in the request body) and API key (in the header) Both can be located in the Dashboard section of your merchant account login.

The request body structure is shown on the request body of the example request shown here.

The following (see table below) are the mandatory parameters that are required to create a purchase request.

Parameters in the request body:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Notes
client.full_name	Conditional. But Recommended to pass the complete name of the client. Atleast 2 words recommended.
client.email	Conditional. But Recommended to pass a correct email id.
paymentMethod	Conditional. Mandatory if you are not using Paybomb Cashier. Else Non Mandatory. Value: APPLEPAY
purchase.currency	Mandatory. ISO 4217 code for currency you want to send the transaction in. This should be 'BRL' for PIX.
purchase.products.name	Mandatory.
purchase.products.price	Mandatory. Price in decimal format upto 2 decimals. example 1: EUR 5 , should be sent as 5.00 example 2: USD 10 and 37 cents , should be sent as 10.37
brand_id	Mandatory. Obtain from Dashboard section of your merchant account login.
success_redirect	Mandatory. URL to send the user if the transactions is successful.
pending_redirect	Mandatory. URL to send the user if the transactions is in progress state.
failure_redirect	Mandatory URL to send the user if the transactions has failed.

Optional Parameters

expireInMin

merchantRef

The merchantRef parameter, although not mandatory, is strongly advised for merchants to specify. Its inclusion offers two significant advantages for the merchant:

Prevention of Duplicate Requests: When a merchantRef is utilized, it acts as a unique identifier. This means that if a second purchase request is made using the same merchantRef (reference number), the system will recognize it and prevent duplicate transactions from occurring. This prevents unintended or duplicate purchases.
\n
Facilitation of Transaction Retrieval: In situations where the response from the initial purchase request times out or the 'purchaseId' isn't received, having the merchantRef allows the merchant to retrieve detailed transaction information. This ensures they can track and access the specific purchase details related to that reference, even if the immediate response was not received.
\n

However, if the merchant does not specify the 'merchantRef' parameter, the platform will automatically assign and use an internal 'purchaseId' as a reference for that transaction.

paymentMethod

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"d8f27861-65fd-4f57-8c8d-92d00fa7558e","id":"d8f27861-65fd-4f57-8c8d-92d00fa7558e","name":"APIs","type":"folder"}},"urlObject":{"path":["purchases",""],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"2106dd8e-74be-4381-8331-ac448033c15c","name":"Purchase - success","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer Token"}],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"email\": \"customer@example.com\"\r\n },\r\n \"purchase\": {\r\n \"currency\": \"USD\",\r\n \"products\": [\r\n {\r\n \"name\": \"Product\",\r\n \"price\": \"10.00\"\r\n }\r\n ]\r\n },\r\n \"paymentMethod\": \"APPLEPAY\",\r\n \"brand_id\": \"your_brand_id\",\r\n \"success_redirect\": \"https://success.com\",\r\n \"pending_redirect\": \"https://pending.com\",\r\n \"failure_redirect\": \"https://failure.com\",\r\n \"extraParam\": {\r\n \"applepay_param\": {\r\n \"applepay_decrypted_payload\": {\r\n \"applicationPrimaryAccountNumber\": \"4111111111111111\",\r\n \"applicationExpirationDate\": \"2712\",\r\n \"currencyCode\": \"840\",\r\n \"transactionAmount\": 1000,\r\n \"deviceManufacturerIdentifier\": \"040010030273\",\r\n \"paymentDataType\": \"3DSecure\",\r\n \"paymentData\": {\r\n \"onlinePaymentCryptogram\": \"AgAAAAAABk4D...\",\r\n \"eciIndicator\": \"05\"\r\n }\r\n }\r\n }\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/purchases"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"purchaseId\": \"69cce01f5bae56fd5547a993\",\r\n \"client\": {\r\n \"customerId\": \"NA\",\r\n \"email\": \"himanshu1@paybomb.tech\",\r\n \"full_name\": \"OpHM\",\r\n \"date_of_birth\": \"1800-01-01\",\r\n \"street_address\": \"SB-124\",\r\n \"country\": \"BR\",\r\n \"city\": \"DLJPR\",\r\n \"zip_code\": \"110001\",\r\n \"cc\": [],\r\n \"bcc\": [],\r\n \"stateCode\": \"DL\"\r\n },\r\n \"updated_on\": 1775034399,\r\n \"type\": \"purchase\",\r\n \"paymentMethod\": \"APPLEPAY\",\r\n \"amountUnit\": \"MAJOR\",\r\n \"errorMsg\": \"\",\r\n \"errorCode\": \"NA\",\r\n \"force_recurring\": false,\r\n \"created_on\": 1775034399,\r\n \"merchantRef\": \"69cce01f5bae56fd5547a993\",\r\n \"purchase\": {\r\n \"currency\": \"USD\",\r\n \"products\": [\r\n {\r\n \"name\": \"e-commerce\",\r\n \"quantity\": 1.0,\r\n \"price\": 10.0,\r\n \"discount\": 0,\r\n \"tax_percent\": \"0.00\"\r\n }\r\n ],\r\n \"total\": 10.0,\r\n \"requestAmount\": 10.0,\r\n \"language\": \"en\",\r\n \"notes\": \"\",\r\n \"debt\": 0,\r\n \"total_formatted\": 1.0,\r\n \"taxAmount\": 0.0,\r\n \"taxPercent\": 0.0,\r\n \"request_client_details\": [],\r\n \"email_message\": \"\"\r\n },\r\n \"issuer_details\": {\r\n \"website\": \"\",\r\n \"legal_street_address\": \"\",\r\n \"legal_country\": \"\",\r\n \"legal_city\": \"\",\r\n \"legal_zip_code\": \"\",\r\n \"bank_accounts\": [\r\n {}\r\n ],\r\n \"legal_name\": \"Omega Pixel\",\r\n \"brand_name\": \"Omega Pixel\",\r\n \"registration_number\": \"\",\r\n \"tax_number\": \"\"\r\n },\r\n \"transaction_data\": {\r\n \"payment_method\": \"\",\r\n \"flow\": \"payform\",\r\n \"extra\": {},\r\n \"country\": \"\",\r\n \"attempts\": []\r\n },\r\n \"status\": \"CREATED\",\r\n \"status_history\": [\r\n {\r\n \"status\": \"created\",\r\n \"timestamp\": 1775034399\r\n }\r\n ],\r\n \"is_test\": false,\r\n \"brand_id\": \"f1764688-d991-481b-be63-9ee7f33dcd31\",\r\n \"send_receipt\": false,\r\n \"is_recurring_token\": false,\r\n \"skip_capture\": false,\r\n \"reference_generated\": \"PS1032\",\r\n \"issued\": \"2026-04-01\",\r\n \"due\": 1775034399,\r\n \"refund_upto\": 0,\r\n \"cc_descriptor\": \"\",\r\n \"fraudScore\": \"NA\",\r\n \"trustScore\": \"NA\",\r\n \"extraFee\": \"0\",\r\n \"paidOn\": 0,\r\n \"receivedAmt\": 0.0,\r\n \"taxAmount\": 0.0,\r\n \"surcharge\": 0.0,\r\n \"surchargeType\": \"\",\r\n \"sessionId\": \"\",\r\n \"refund_availability\": \"NONE\",\r\n \"refundable_amount\": 0.0,\r\n \"success_redirect\": \"https://google.com/\",\r\n \"failure_redirect\": \"https://facebook.com/\",\r\n \"pending_redirect\": \"https://app.paybomb.tech\",\r\n \"cancel_redirect\": \"\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\",\r\n \"platform\": \"API\",\r\n \"created_from_ip\": \"103.80.161.238\",\r\n \"checkout_url\": \"https://api.choicepay.ca/payments/6b5a5977ac8e022facb31f3346f61ed0/\",\r\n \"direct_post_url\": \"https://api.choicepay.ca/api/v1/p/69cce01f5bae56fd5547a993/\",\r\n \"payoutProcess\": false\r\n}"},{"id":"c2fef133-859a-4f76-b48e-0796bb43bed2","name":"Purchase - failure","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer Token"}],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"email\": \"customer@example.com\"\r\n },\r\n \"purchase\": {\r\n \"currency\": \"USD\",\r\n \"products\": [\r\n {\r\n \"name\": \"Product\",\r\n \"price\": \"10.00\"\r\n }\r\n ]\r\n },\r\n \"paymentMethod\": \"APPLEPAY\",\r\n \"brand_id\": \"your_brand_id\",\r\n \"success_redirect\": \"https://success.com\",\r\n \"pending_redirect\": \"https://pending.com\",\r\n \"failure_redirect\": \"https://failure.com\",\r\n \"extraParam\": {\r\n \"applepay_param\": {\r\n \"applepay_decrypted_payload\": {\r\n \"applicationPrimaryAccountNumber\": \"4111111111111111\",\r\n \"applicationExpirationDate\": \"2712\",\r\n \"currencyCode\": \"840\",\r\n \"transactionAmount\": 1000,\r\n \"deviceManufacturerIdentifier\": \"040010030273\",\r\n \"paymentDataType\": \"3DSecure\",\r\n \"paymentData\": {\r\n \"onlinePaymentCryptogram\": \"AgAAAAAABk4D...\",\r\n \"eciIndicator\": \"05\"\r\n }\r\n }\r\n }\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/purchases"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"message\": \"Error Message\",\r\n \"code\": \"error_code\"\r\n}"}],"_postman_id":"e53e191a-cc48-47a4-9125-bc42c6251680"},{"name":"Get Status","id":"0b0e00d3-bac5-4263-896f-c9cc33cb312a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"url":"https://app.paybomb.tech/api/v1/purchases/{purchaseId}/","description":"

This API tells you about all the details of a purchase (PayIn), including its history

Mandatory

you need to pass the PurchaseID in the API URL

Possible Value of Status

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Notes
paid	Transaction Successful
payment_in_process	Payment is under Processing
expired	Purchase has Expired.
error	Transaction has Failed.

Response Examples

In the response examples you can see instances of both Paid and Error Status purchases.

Error Details

If there are any issues on the Purchase you can get more details from the transaction_data.attempts.error attribute of the response object

Errors

If there are any errors then it'll be in the format of :

{\n    \"message\": \"descriptive error message\",\n    \"code\": \"error_code\"\n}\n\n

Please see the Status Code section for further details.

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"d8f27861-65fd-4f57-8c8d-92d00fa7558e","id":"d8f27861-65fd-4f57-8c8d-92d00fa7558e","name":"APIs","type":"folder"}},"urlObject":{"path":["purchases","{purchaseId}",""],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"484936b0-719b-4acb-b8e5-4329b05748d5","name":"Purchase - success","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer Token"}],"url":"https://app.paybomb.tech/api/v1/purchases/{purchaseId}/"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"purchaseId\": \"69cce01f5bae56fd5547a993\",\r\n \"client\": {\r\n \"customerId\": \"NA\",\r\n \"email\": \"himanshu1@paybomb.tech\",\r\n \"full_name\": \"OpHM\",\r\n \"date_of_birth\": \"1800-01-01\",\r\n \"street_address\": \"SB-124\",\r\n \"country\": \"BR\",\r\n \"city\": \"DLJPR\",\r\n \"zip_code\": \"110001\",\r\n \"cc\": [],\r\n \"bcc\": [],\r\n \"stateCode\": \"DL\"\r\n },\r\n \"updated_on\": 1775034399,\r\n \"type\": \"purchase\",\r\n \"paymentMethod\": \"GOOGLEPAY\",\r\n \"amountUnit\": \"MAJOR\",\r\n \"errorMsg\": \"\",\r\n \"errorCode\": \"NA\",\r\n \"force_recurring\": false,\r\n \"created_on\": 1775034399,\r\n \"merchantRef\": \"69cce01f5bae56fd5547a993\",\r\n \"purchase\": {\r\n \"currency\": \"USD\",\r\n \"products\": [\r\n {\r\n \"name\": \"e-commerce\",\r\n \"quantity\": 1.0,\r\n \"price\": 10.0,\r\n \"discount\": 0,\r\n \"tax_percent\": \"0.00\"\r\n }\r\n ],\r\n \"total\": 10.0,\r\n \"requestAmount\": 10.0,\r\n \"language\": \"en\",\r\n \"notes\": \"\",\r\n \"debt\": 0,\r\n \"total_formatted\": 1.0,\r\n \"taxAmount\": 0.0,\r\n \"taxPercent\": 0.0,\r\n \"request_client_details\": [],\r\n \"email_message\": \"\"\r\n },\r\n \"issuer_details\": {\r\n \"website\": \"\",\r\n \"legal_street_address\": \"\",\r\n \"legal_country\": \"\",\r\n \"legal_city\": \"\",\r\n \"legal_zip_code\": \"\",\r\n \"bank_accounts\": [\r\n {}\r\n ],\r\n \"legal_name\": \"Omega Pixel\",\r\n \"brand_name\": \"Omega Pixel\",\r\n \"registration_number\": \"\",\r\n \"tax_number\": \"\"\r\n },\r\n \"transaction_data\": {\r\n \"payment_method\": \"\",\r\n \"flow\": \"payform\",\r\n \"extra\": {},\r\n \"country\": \"\",\r\n \"attempts\": []\r\n },\r\n \"status\": \"CREATED\",\r\n \"status_history\": [\r\n {\r\n \"status\": \"created\",\r\n \"timestamp\": 1775034399\r\n }\r\n ],\r\n \"is_test\": false,\r\n \"brand_id\": \"f1764688-d991-481b-be63-9ee7f33dcd31\",\r\n \"send_receipt\": false,\r\n \"is_recurring_token\": false,\r\n \"skip_capture\": false,\r\n \"reference_generated\": \"PS1032\",\r\n \"issued\": \"2026-04-01\",\r\n \"due\": 1775034399,\r\n \"refund_upto\": 0,\r\n \"cc_descriptor\": \"\",\r\n \"fraudScore\": \"NA\",\r\n \"trustScore\": \"NA\",\r\n \"extraFee\": \"0\",\r\n \"paidOn\": 0,\r\n \"receivedAmt\": 0.0,\r\n \"taxAmount\": 0.0,\r\n \"surcharge\": 0.0,\r\n \"surchargeType\": \"\",\r\n \"sessionId\": \"\",\r\n \"refund_availability\": \"NONE\",\r\n \"refundable_amount\": 0.0,\r\n \"success_redirect\": \"https://google.com/\",\r\n \"failure_redirect\": \"https://facebook.com/\",\r\n \"pending_redirect\": \"https://app.paybomb.tech\",\r\n \"cancel_redirect\": \"\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\",\r\n \"platform\": \"API\",\r\n \"created_from_ip\": \"103.80.161.238\",\r\n \"checkout_url\": \"https://api.choicepay.ca/payments/6b5a5977ac8e022facb31f3346f61ed0/\",\r\n \"direct_post_url\": \"https://api.choicepay.ca/api/v1/p/69cce01f5bae56fd5547a993/\",\r\n \"payoutProcess\": false\r\n}"},{"id":"fa01cf26-0abe-49b3-8c86-5dff1b001d65","name":"Purchase - failure","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"url":"https://app.paybomb.tech/api/v1/purchases/{purchaseId}/"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"message\": \"Error Message\",\r\n \"code\": \"error_code\"\r\n}"}],"_postman_id":"0b0e00d3-bac5-4263-896f-c9cc33cb312a"}],"id":"d8f27861-65fd-4f57-8c8d-92d00fa7558e","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"162f8af0-6223-4bf1-8771-305a947651b3"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"242771cd-eab9-451a-9f25-16752ef78b12"}}],"_postman_id":"d8f27861-65fd-4f57-8c8d-92d00fa7558e","description":""}],"id":"543e945e-e2ab-4d45-9e7f-7846fadf8f19","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"8f649ede-2d7b-4edc-ac00-1b987a71e95d"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"ba5b300d-9540-49fd-9e13-07d9380404c6"}}],"_postman_id":"543e945e-e2ab-4d45-9e7f-7846fadf8f19","description":""}],"id":"ee6708dd-bd6f-47cc-bee8-e56002ce1f8f","_postman_id":"ee6708dd-bd6f-47cc-bee8-e56002ce1f8f","description":""}],"id":"80cdee1d-b7b0-43db-bd12-183de874912b","_postman_id":"80cdee1d-b7b0-43db-bd12-183de874912b","description":""},{"name":"Trust Score","item":[{"name":"TrustScore Detailed","id":"31d40cc1-df1f-4ea5-99d0-478ea82a4ade","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"requiredinput\": {\r\n \"ip\": \"111.11.11.11\",\r\n \"email\": \"test@gmail.com\",\r\n \"url\": \"https://www.asos.com/\"\r\n },\r\n \"optionalInput\": {\r\n \"last_bets\": null,\r\n \"last_wins\": \"\",\r\n \"total_bonuses\": \"\",\r\n \"last_real_bets\": \"\",\r\n \"last_real_wins\": \"\",\r\n \"total_deposits\": \"\",\r\n \"last_bonus_bets\": \"\",\r\n \"last_bonus_wins\": \"\",\r\n \"average_real_bet\": \"\",\r\n \"last_bets_amount\": \"\",\r\n \"last_wins_amount\": \"\",\r\n \"average_bonus_bet\": \"\",\r\n \"bonus_to_deposits\": \"\",\r\n \"last_deposit_date\": \"\",\r\n \"total_withdrawals\": \"\",\r\n \"is_phone_confirmed\": \"\",\r\n \"money_in_money_out\": \"\",\r\n \"last_deposit_amount\": \"\",\r\n \"last_freespins_date\": \"\",\r\n \"last_freespins_name\": \"\",\r\n \"last_free_bonus_date\": \"\",\r\n \"last_free_bonus_name\": \"\",\r\n \"total_bonuses_amount\": \"\",\r\n \"last_freespins_amount\": \"\",\r\n \"last_freespins_status\": \"\",\r\n \"last_real_bets_amount\": \"\",\r\n \"last_real_wins_amount\": \"\",\r\n \"total_deposits_amount\": \"\",\r\n \"last_bonus_bets_amount\": \"\",\r\n \"last_bonus_wins_amount\": \"\",\r\n \"last_free_bonus_amount\": \"\",\r\n \"last_free_bonus_status\": \"\",\r\n \"last_deposit_bonus_date\": \"\",\r\n \"last_deposit_bonus_name\": \"\",\r\n \"last_freespins_currency\": \"\",\r\n \"last_freespins_wagering\": \"\",\r\n \"withdrawals_to_deposits\": \"\",\r\n \"last_free_bonus_currency\": \"\",\r\n \"last_free_bonus_wagering\": \"\",\r\n \"total_withdrawals_amount\": \"\",\r\n \"withdrawal_ewallet_email\": \"\",\r\n \"last_deposit_bonus_amount\": \"\",\r\n \"last_deposit_bonus_status\": \"\",\r\n \"last_deposit_bonus_currency\": \"\",\r\n \"last_deposit_bonus_wagering\": \"\",\r\n \"session\": \"\",\r\n \"payment_mode\": \"\",\r\n \"card_fullname\": \"\",\r\n \"card_bin\": \"\",\r\n \"card_hash\": \"\",\r\n \"card_last\": \"\",\r\n \"card_expire\": \"\",\r\n \"avs_result\": \"\",\r\n \"cvv_result\": \"\",\r\n \"sca_method\": \"\",\r\n \"user_bank_account\": \"\",\r\n \"user_bank_name\": \"\",\r\n \"user_balance\": \"\",\r\n \"user_verification_level\": \"\",\r\n \"status_3d\": \"\",\r\n \"regulation\": \"\",\r\n \"payment_provider\": \"\",\r\n \"phone_number\": \"\",\r\n \"transaction_type\": \"\",\r\n \"transaction_amount\": \"\",\r\n \"transaction_currency\": \"\",\r\n \"merchant_id\": \"\",\r\n \"details_url\": \"\",\r\n \"name\": \"\",\r\n \"person_type\": \"\",\r\n \"gender\": \"\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/trustScore","description":"

Overview

Paybomb TrustScore's proprietary API combines email, phone number, IP and URL so that you can request and receive a user trust score from our enriched data, rules, and scoring in a single API call.

Our take on Trust is different from the usual approach to fraud. This API tells you how much you can trust this user. It’s based on 100+ data points to which we have access. We use complex algorithms based on data sanity and customer behaviour in our partner network.

Also, the additional optional parameter would be used to boost the accuracy of our response. So the more data we get the better we can ascertain the users' trust. So please endeavour to send as much information about the user as possible.

Trust Score & Usage

TrustScore offers two distinct endpoints: General and Detailed.

The General endpoint provides basic information by indicating whether a transaction is permitted or not. It gives a simple 'yes' or 'no' response regarding whether the transaction can proceed.

On the other hand, the Detailed endpoint offers a more comprehensive evaluation. It furnishes an in-depth analysis of the transaction's authenticity, providing a detailed assessment beyond a simple allowance or denial, offering nuanced insights and information about the transaction's legitimacy.

Detailed TrustScore

Trust scores range from 0 to 5. A trust score of 0 indicates that we have limited information about the user, and it corresponds to the lowest level of trust. In addition to the TrustScore, we offer eight other flags to help assess the user's overall profile and determine appropriate actions to take. We suggest flagging or blocking users, transactions, or clicks as high risk based on a combination of the following factors: email deliverability, proxy usage, VPN usage, Tor usage, and recent abusive behavior.

Every company has a unique target audience, so you might achieve better results by only flagging or blocking entities with low trust scores and recent instances of abuse. Keep in mind that mobile IP addresses are frequently misused and recycled by mobile carriers. Therefore, for mobile lookups, we advise giving more weight to the trust score, VPN usage, and Tor usage, as opposed to proxy usage.

Permission

Access to this API has to be given to you by the admin. So please contact your sales representative at Paybomb to get access to this API, if you get a 401 error of \"You are not allowed to call this API service\".

Mandatory Parameters (in body)

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameters	Description
ip	IP of the user. Both IP4 and IP6 are valid
email	The email id of the user you want to trust score on
url	The URL on which the user is trying to purchase or consume a product, service or data.

Other optional paramters:

The optional parameters are self-explanatory and appropriate values can be given in string format.

Parameters	Values
last_bets	String
last_wins	String
total_bonuses	String
last_real_bets	String
last_real_wins	String
total_deposits	String
last_bonus_bets	String
last_bonus_wins	String
average_real_bet	String
last_bets_amount	String
last_wins_amount	String
average_bonus_bet	String
bonus_to_deposits	String
last_deposit_date	String
total_withdrawals	String
is_phone_confirmed	String
money_in_money_out	String
last_deposit_amount	String
last_freespins_date	String
last_freespins_name	String
last_free_bonus_date	String
last_free_bonus_name	String
total_bonuses_amount	String
last_freespins_amount	String
last_freespins_status	String
last_real_bets_amount	String
last_real_wins_amount	String
total_deposits_amount	String
last_bonus_bets_amount	String
last_bonus_wins_amount	String
last_free_bonus_amount	String
last_free_bonus_status	String
last_deposit_bonus_date	String
last_deposit_bonus_name	String
last_freespins_currency	String
last_freespins_wagering	String
withdrawals_to_deposits	String
last_free_bonus_currency	String
last_free_bonus_wagering	String
total_withdrawals_amount	String
withdrawal_ewallet_email	String
last_deposit_bonus_amount	String
last_deposit_bonus_status	String
last_deposit_bonus_currency	String
last_deposit_bonus_wagering	String
session	String
payment_mode	String
card_fullname	String
card_bin	String
card_hash	String
card_last	String
card_expire	String
avs_result	String
cvv_result	String
sca_method	String
user_bank_account	String
user_bank_name	String
user_balance	String
user_verification_level	String
status_3d	String
regulation	String
payment_provider	String
phone_number	String
transaction_type	String
transaction_amount	String
transaction_currency	String
merchant_id	String
details_url	String
name	String
person_type	String
gender	String

Response

In the response examples, you can observe both instances of a successful TrustScore response and an unsuccessful one.

Please note that there are a lot of parameters to determine the trust level and give you some additional details on the email and IP of the user.

in a successful trust score call the following data would be provided:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Response Item	Description	Possible Values
trustScore	The trust score attributed to the user by our algorithms	Integer 0 to 5
deliverable	Whether the email is deliverable, usually false means it wouldn't be a trustable user.	Boolean
proxy	Is this IP address suspected to be a proxy? (SOCKS, Elite, Anonymous, VPN, Tor, etc.)	Boolean
vpn	Is this IP suspected of being a VPN connection? This can include data center ranges which can become active VPNs at any time. The \"proxy\" status will always be true when this value is true.	Boolean
tor	Is this IP suspected of being a TOR connection? This can include previously active TOR nodes and exits which can become active TOR exits at any time. The \"proxy\" status will always be true when this value is true.	Boolean
active_vpn	Identifies active VPN connections used by popular VPN services and private VPN servers.	Boolean
active_tor	Identifies active TOR exits on the TOR network.	Boolean
recent_abuse	This value indicates whether the IP address has been associated with any recently verified abuse on our network, such as a confirmed chargeback, compromised device, or fake app install.	Boolean
bot_status	Shows whether bots or non-human traffic recently used this IP address to engage in automated fraud. This provides strong evidence that the IP address is suspicious.	Boolean

Errors

If there are any errors then it'll be in the format of :

{\n    \"message\": \"descriptive error message\",\n    \"code\": \"error_code\"\n}\n\n

Possible Error Messages

the possible error codes one can get on calling this APIs are:

\n\n\n\n\n\n\n\n\n\n\n

Code
400, 404, 401, 415, 405

for example:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Code	Error Messages
401	Incorrect secret_key
401	You are not Allowed to call this API service

","urlObject":{"path":["trustScore"],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"164e2fe9-526f-4d4a-9e3e-1404463f5f14","name":"TrustScoreExists","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"requiredinput\": {\r\n \"ip\": \"2001:8004:cc2:fadb:9958:4523:6c42:e3f2\",\r\n \"email\": \"test@gmail.com\",\r\n \"url\": \"http://test.com\"\r\n },\r\n \"optionalInput\": {\r\n \"last_bets\": null,\r\n \"last_wins\": \"\",\r\n \"total_bonuses\": \"\",\r\n \"last_real_bets\": \"\",\r\n \"last_real_wins\": \"\",\r\n \"total_deposits\": \"\",\r\n \"last_bonus_bets\": \"\",\r\n \"last_bonus_wins\": \"\",\r\n \"average_real_bet\": \"\",\r\n \"last_bets_amount\": \"\",\r\n \"last_wins_amount\": \"\",\r\n \"average_bonus_bet\": \"\",\r\n \"bonus_to_deposits\": \"\",\r\n \"last_deposit_date\": \"\",\r\n \"total_withdrawals\": \"\",\r\n \"is_phone_confirmed\": \"\",\r\n \"money_in_money_out\": \"\",\r\n \"last_deposit_amount\": \"\",\r\n \"last_freespins_date\": \"\",\r\n \"last_freespins_name\": \"\",\r\n \"last_free_bonus_date\": \"\",\r\n \"last_free_bonus_name\": \"\",\r\n \"total_bonuses_amount\": \"\",\r\n \"last_freespins_amount\": \"\",\r\n \"last_freespins_status\": \"\",\r\n \"last_real_bets_amount\": \"\",\r\n \"last_real_wins_amount\": \"\",\r\n \"total_deposits_amount\": \"\",\r\n \"last_bonus_bets_amount\": \"\",\r\n \"last_bonus_wins_amount\": \"\",\r\n \"last_free_bonus_amount\": \"\",\r\n \"last_free_bonus_status\": \"\",\r\n \"last_deposit_bonus_date\": \"\",\r\n \"last_deposit_bonus_name\": \"\",\r\n \"last_freespins_currency\": \"\",\r\n \"last_freespins_wagering\": \"\",\r\n \"withdrawals_to_deposits\": \"\",\r\n \"last_free_bonus_currency\": \"\",\r\n \"last_free_bonus_wagering\": \"\",\r\n \"total_withdrawals_amount\": \"\",\r\n \"withdrawal_ewallet_email\": \"\",\r\n \"last_deposit_bonus_amount\": \"\",\r\n \"last_deposit_bonus_status\": \"\",\r\n \"last_deposit_bonus_currency\": \"\",\r\n \"last_deposit_bonus_wagering\": \"\",\r\n \"session\": \"\",\r\n \"payment_mode\": \"\",\r\n \"card_fullname\": \"\",\r\n \"card_bin\": \"\",\r\n \"card_hash\": \"\",\r\n \"card_last\": \"\",\r\n \"card_expire\": \"\",\r\n \"avs_result\": \"\",\r\n \"cvv_result\": \"\",\r\n \"sca_method\": \"\",\r\n \"user_bank_account\": \"\",\r\n \"user_bank_name\": \"\",\r\n \"user_balance\": \"\",\r\n \"user_verification_level\": \"\",\r\n \"status_3d\": \"\",\r\n \"regulation\": \"\",\r\n \"payment_provider\": \"\",\r\n \"phone_number\": \"\",\r\n \"transaction_type\": \"\",\r\n \"transaction_amount\": \"\",\r\n \"transaction_currency\": \"\",\r\n \"merchant_id\": \"\",\r\n \"details_url\": \"\",\r\n \"name\": \"\",\r\n \"person_type\": \"\",\r\n \"gender\": \"\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"{{StagingBaseURL}}/trustScore"},"status":"Accepted","code":202,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Sun, 29 Oct 2023 09:21:22 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"1; mode=block"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"X-Frame-Options","value":"DENY"},{"key":"CF-Cache-Status","value":"DYNAMIC"},{"key":"Report-To","value":"{\"endpoints\":[{\"url\":\"https:\\/\\/a.nel.cloudflare.com\\/report\\/v3?s=r2%2FuLwSilxdD1lpiI1VqpgF0Tu9etiNhupySeBHl0zcU8XV1z8kwR%2FJ00ti4xpMdrTXW%2BkqZkLGrkkaUnMWFsaYlg%2FfA9UC4wIKwmc9LHUwna491EmnC3b3vlabzhUJ11CMpnVmicUE%3D\"}],\"group\":\"cf-nel\",\"max_age\":604800}"},{"key":"NEL","value":"{\"success_fraction\":0,\"report_to\":\"cf-nel\",\"max_age\":604800}"},{"key":"Server","value":"cloudflare"},{"key":"CF-RAY","value":"81da590e8d4345a0-LHR"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"trustScore\": 0,\n \"deliverable\": \"false\",\n \"proxy\": \"false\",\n \"vpn\": \"false\",\n \"tor\": \"false\",\n \"active_vpn\": \"false\",\n \"active_tor\": \"false\",\n \"recent_abuse\": \"false\",\n \"bot_status\": \"false\"\n}"},{"id":"572cf128-a0fd-4d32-8f49-2c99058a7e8e","name":"TrustScoreError","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"requiredinput\": {\r\n \"ip\": \"2001:8004:cc2:fadb:9958:4523:6c42:e3f2\",\r\n \"email\": \"test@gmail.com\",\r\n \"url\": \"http://test.com\"\r\n },\r\n \"optionalInput\": {\r\n \"last_bets\": null,\r\n \"last_wins\": \"\",\r\n \"total_bonuses\": \"\",\r\n \"last_real_bets\": \"\",\r\n \"last_real_wins\": \"\",\r\n \"total_deposits\": \"\",\r\n \"last_bonus_bets\": \"\",\r\n \"last_bonus_wins\": \"\",\r\n \"average_real_bet\": \"\",\r\n \"last_bets_amount\": \"\",\r\n \"last_wins_amount\": \"\",\r\n \"average_bonus_bet\": \"\",\r\n \"bonus_to_deposits\": \"\",\r\n \"last_deposit_date\": \"\",\r\n \"total_withdrawals\": \"\",\r\n \"is_phone_confirmed\": \"\",\r\n \"money_in_money_out\": \"\",\r\n \"last_deposit_amount\": \"\",\r\n \"last_freespins_date\": \"\",\r\n \"last_freespins_name\": \"\",\r\n \"last_free_bonus_date\": \"\",\r\n \"last_free_bonus_name\": \"\",\r\n \"total_bonuses_amount\": \"\",\r\n \"last_freespins_amount\": \"\",\r\n \"last_freespins_status\": \"\",\r\n \"last_real_bets_amount\": \"\",\r\n \"last_real_wins_amount\": \"\",\r\n \"total_deposits_amount\": \"\",\r\n \"last_bonus_bets_amount\": \"\",\r\n \"last_bonus_wins_amount\": \"\",\r\n \"last_free_bonus_amount\": \"\",\r\n \"last_free_bonus_status\": \"\",\r\n \"last_deposit_bonus_date\": \"\",\r\n \"last_deposit_bonus_name\": \"\",\r\n \"last_freespins_currency\": \"\",\r\n \"last_freespins_wagering\": \"\",\r\n \"withdrawals_to_deposits\": \"\",\r\n \"last_free_bonus_currency\": \"\",\r\n \"last_free_bonus_wagering\": \"\",\r\n \"total_withdrawals_amount\": \"\",\r\n \"withdrawal_ewallet_email\": \"\",\r\n \"last_deposit_bonus_amount\": \"\",\r\n \"last_deposit_bonus_status\": \"\",\r\n \"last_deposit_bonus_currency\": \"\",\r\n \"last_deposit_bonus_wagering\": \"\",\r\n \"session\": \"\",\r\n \"payment_mode\": \"\",\r\n \"card_fullname\": \"\",\r\n \"card_bin\": \"\",\r\n \"card_hash\": \"\",\r\n \"card_last\": \"\",\r\n \"card_expire\": \"\",\r\n \"avs_result\": \"\",\r\n \"cvv_result\": \"\",\r\n \"sca_method\": \"\",\r\n \"user_bank_account\": \"\",\r\n \"user_bank_name\": \"\",\r\n \"user_balance\": \"\",\r\n \"user_verification_level\": \"\",\r\n \"status_3d\": \"\",\r\n \"regulation\": \"\",\r\n \"payment_provider\": \"\",\r\n \"phone_number\": \"\",\r\n \"transaction_type\": \"\",\r\n \"transaction_amount\": \"\",\r\n \"transaction_currency\": \"\",\r\n \"merchant_id\": \"\",\r\n \"details_url\": \"\",\r\n \"name\": \"\",\r\n \"person_type\": \"\",\r\n \"gender\": \"\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"{{StagingBaseURL}}/trustScore"},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Sun, 29 Oct 2023 09:28:33 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"1; mode=block"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"X-Frame-Options","value":"DENY"},{"key":"CF-Cache-Status","value":"DYNAMIC"},{"key":"Report-To","value":"{\"endpoints\":[{\"url\":\"https:\\/\\/a.nel.cloudflare.com\\/report\\/v3?s=herXY1o%2BFZa%2F3qNFjvh4ANgP%2FD0DdAVVFm0vUZDAst2rFkieItm%2Fu0VN24DYrdp7MHMHFKWLvrsBYVIxjDPDaLgJjeGBvlTP2iZoB5EnG1hPPHUVXRNP%2FGMmOTh%2Fp7gsyj0vihW1kMk%3D\"}],\"group\":\"cf-nel\",\"max_age\":604800}"},{"key":"NEL","value":"{\"success_fraction\":0,\"report_to\":\"cf-nel\",\"max_age\":604800}"},{"key":"Server","value":"cloudflare"},{"key":"CF-RAY","value":"81da6398ab144913-LHR"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"Incorrect secret_key\",\n \"code\": \"authentication_failed\"\n}"}],"_postman_id":"31d40cc1-df1f-4ea5-99d0-478ea82a4ade"},{"name":"checkTransactionAllowed","id":"bfc94c6f-0b33-4110-b70c-20fd1565bacf","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"requiredinput\": {\r\n \"ip\": \"111.11.11.11\",\r\n \"email\": \"test@gmail.com\",\r\n \"url\": \"https://www.asos.com/\"\r\n },\r\n \"optionalInput\": {\r\n \"last_bets\": null,\r\n \"last_wins\": \"\",\r\n \"total_bonuses\": \"\",\r\n \"last_real_bets\": \"\",\r\n \"last_real_wins\": \"\",\r\n \"total_deposits\": \"\",\r\n \"last_bonus_bets\": \"\",\r\n \"last_bonus_wins\": \"\",\r\n \"average_real_bet\": \"\",\r\n \"last_bets_amount\": \"\",\r\n \"last_wins_amount\": \"\",\r\n \"average_bonus_bet\": \"\",\r\n \"bonus_to_deposits\": \"\",\r\n \"last_deposit_date\": \"\",\r\n \"total_withdrawals\": \"\",\r\n \"is_phone_confirmed\": \"\",\r\n \"money_in_money_out\": \"\",\r\n \"last_deposit_amount\": \"\",\r\n \"last_freespins_date\": \"\",\r\n \"last_freespins_name\": \"\",\r\n \"last_free_bonus_date\": \"\",\r\n \"last_free_bonus_name\": \"\",\r\n \"total_bonuses_amount\": \"\",\r\n \"last_freespins_amount\": \"\",\r\n \"last_freespins_status\": \"\",\r\n \"last_real_bets_amount\": \"\",\r\n \"last_real_wins_amount\": \"\",\r\n \"total_deposits_amount\": \"\",\r\n \"last_bonus_bets_amount\": \"\",\r\n \"last_bonus_wins_amount\": \"\",\r\n \"last_free_bonus_amount\": \"\",\r\n \"last_free_bonus_status\": \"\",\r\n \"last_deposit_bonus_date\": \"\",\r\n \"last_deposit_bonus_name\": \"\",\r\n \"last_freespins_currency\": \"\",\r\n \"last_freespins_wagering\": \"\",\r\n \"withdrawals_to_deposits\": \"\",\r\n \"last_free_bonus_currency\": \"\",\r\n \"last_free_bonus_wagering\": \"\",\r\n \"total_withdrawals_amount\": \"\",\r\n \"withdrawal_ewallet_email\": \"\",\r\n \"last_deposit_bonus_amount\": \"\",\r\n \"last_deposit_bonus_status\": \"\",\r\n \"last_deposit_bonus_currency\": \"\",\r\n \"last_deposit_bonus_wagering\": \"\",\r\n \"session\": \"\",\r\n \"payment_mode\": \"\",\r\n \"card_fullname\": \"\",\r\n \"card_bin\": \"\",\r\n \"card_hash\": \"\",\r\n \"card_last\": \"\",\r\n \"card_expire\": \"\",\r\n \"avs_result\": \"\",\r\n \"cvv_result\": \"\",\r\n \"sca_method\": \"\",\r\n \"user_bank_account\": \"\",\r\n \"user_bank_name\": \"\",\r\n \"user_balance\": \"\",\r\n \"user_verification_level\": \"\",\r\n \"status_3d\": \"\",\r\n \"regulation\": \"\",\r\n \"payment_provider\": \"\",\r\n \"phone_number\": \"\",\r\n \"transaction_type\": \"\",\r\n \"transaction_amount\": \"\",\r\n \"transaction_currency\": \"\",\r\n \"merchant_id\": \"\",\r\n \"details_url\": \"\",\r\n \"name\": \"\",\r\n \"person_type\": \"\",\r\n \"gender\": \"\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/checkTransAllowed","description":"

General TrustScore

Request for the checkTransactionAllowed endpoint is identical to the TrustScore API. Only thing different is the response. Instead of detailed score, this endpoint only returns transactionAllowed parameter that can have either YES or NO value.

Permission

Mandatory Parameters (in body)

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameters	Description
ip	IP of the user. Both IP4 and IP6 are valid
email	The email id of the user you want to trust score on
url	The URL on which the user is trying to purchase or consume a product, service or data.

Other optional paramters:

The optional parameters are self-explanatory and appropriate values can be given in string format.

Parameters	Values
last_bets	String
last_wins	String
total_bonuses	String
last_real_bets	String
last_real_wins	String
total_deposits	String
last_bonus_bets	String
last_bonus_wins	String
average_real_bet	String
last_bets_amount	String
last_wins_amount	String
average_bonus_bet	String
bonus_to_deposits	String
last_deposit_date	String
total_withdrawals	String
is_phone_confirmed	String
money_in_money_out	String
last_deposit_amount	String
last_freespins_date	String
last_freespins_name	String
last_free_bonus_date	String
last_free_bonus_name	String
total_bonuses_amount	String
last_freespins_amount	String
last_freespins_status	String
last_real_bets_amount	String
last_real_wins_amount	String
total_deposits_amount	String
last_bonus_bets_amount	String
last_bonus_wins_amount	String
last_free_bonus_amount	String
last_free_bonus_status	String
last_deposit_bonus_date	String
last_deposit_bonus_name	String
last_freespins_currency	String
last_freespins_wagering	String
withdrawals_to_deposits	String
last_free_bonus_currency	String
last_free_bonus_wagering	String
total_withdrawals_amount	String
withdrawal_ewallet_email	String
last_deposit_bonus_amount	String
last_deposit_bonus_status	String
last_deposit_bonus_currency	String
last_deposit_bonus_wagering	String
session	String
payment_mode	String
card_fullname	String
card_bin	String
card_hash	String
card_last	String
card_expire	String
avs_result	String
cvv_result	String
sca_method	String
user_bank_account	String
user_bank_name	String
user_balance	String
user_verification_level	String
status_3d	String
regulation	String
payment_provider	String
phone_number	String
transaction_type	String
transaction_amount	String
transaction_currency	String
merchant_id	String
details_url	String
name	String
person_type	String
gender	String

Response

Response contains a single parameter: transactionAllowed which can either be YES or NO .

{\n\"transactionAllowed\" : \"YES\"\n}\n\n

If there are any errors then it'll be in the format of :

{\n    \"message\": \"descriptive error message\",\n    \"code\": \"error_code\"\n}\n\n

Possible Error Messages

the possible error codes one can get on calling this APIs are:

\n\n\n\n\n\n\n\n\n\n\n

Code
400, 404, 401, 415, 405

for example:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Code	Error Messages
401	Incorrect secret_key
401	You are not Allowed to call this API service

","urlObject":{"path":["checkTransAllowed"],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"33e9ac42-ca84-4735-9492-7e065a434728","name":"TrustScoreExists","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"requiredinput\": {\r\n \"ip\": \"2001:8004:cc2:fadb:9958:4523:6c42:e3f2\",\r\n \"email\": \"test@gmail.com\",\r\n \"url\": \"http://test.com\"\r\n },\r\n \"optionalInput\": {\r\n \"last_bets\": null,\r\n \"last_wins\": \"\",\r\n \"total_bonuses\": \"\",\r\n \"last_real_bets\": \"\",\r\n \"last_real_wins\": \"\",\r\n \"total_deposits\": \"\",\r\n \"last_bonus_bets\": \"\",\r\n \"last_bonus_wins\": \"\",\r\n \"average_real_bet\": \"\",\r\n \"last_bets_amount\": \"\",\r\n \"last_wins_amount\": \"\",\r\n \"average_bonus_bet\": \"\",\r\n \"bonus_to_deposits\": \"\",\r\n \"last_deposit_date\": \"\",\r\n \"total_withdrawals\": \"\",\r\n \"is_phone_confirmed\": \"\",\r\n \"money_in_money_out\": \"\",\r\n \"last_deposit_amount\": \"\",\r\n \"last_freespins_date\": \"\",\r\n \"last_freespins_name\": \"\",\r\n \"last_free_bonus_date\": \"\",\r\n \"last_free_bonus_name\": \"\",\r\n \"total_bonuses_amount\": \"\",\r\n \"last_freespins_amount\": \"\",\r\n \"last_freespins_status\": \"\",\r\n \"last_real_bets_amount\": \"\",\r\n \"last_real_wins_amount\": \"\",\r\n \"total_deposits_amount\": \"\",\r\n \"last_bonus_bets_amount\": \"\",\r\n \"last_bonus_wins_amount\": \"\",\r\n \"last_free_bonus_amount\": \"\",\r\n \"last_free_bonus_status\": \"\",\r\n \"last_deposit_bonus_date\": \"\",\r\n \"last_deposit_bonus_name\": \"\",\r\n \"last_freespins_currency\": \"\",\r\n \"last_freespins_wagering\": \"\",\r\n \"withdrawals_to_deposits\": \"\",\r\n \"last_free_bonus_currency\": \"\",\r\n \"last_free_bonus_wagering\": \"\",\r\n \"total_withdrawals_amount\": \"\",\r\n \"withdrawal_ewallet_email\": \"\",\r\n \"last_deposit_bonus_amount\": \"\",\r\n \"last_deposit_bonus_status\": \"\",\r\n \"last_deposit_bonus_currency\": \"\",\r\n \"last_deposit_bonus_wagering\": \"\",\r\n \"session\": \"\",\r\n \"payment_mode\": \"\",\r\n \"card_fullname\": \"\",\r\n \"card_bin\": \"\",\r\n \"card_hash\": \"\",\r\n \"card_last\": \"\",\r\n \"card_expire\": \"\",\r\n \"avs_result\": \"\",\r\n \"cvv_result\": \"\",\r\n \"sca_method\": \"\",\r\n \"user_bank_account\": \"\",\r\n \"user_bank_name\": \"\",\r\n \"user_balance\": \"\",\r\n \"user_verification_level\": \"\",\r\n \"status_3d\": \"\",\r\n \"regulation\": \"\",\r\n \"payment_provider\": \"\",\r\n \"phone_number\": \"\",\r\n \"transaction_type\": \"\",\r\n \"transaction_amount\": \"\",\r\n \"transaction_currency\": \"\",\r\n \"merchant_id\": \"\",\r\n \"details_url\": \"\",\r\n \"name\": \"\",\r\n \"person_type\": \"\",\r\n \"gender\": \"\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"{{StagingBaseURL}}/checkTransAllowed"},"status":"Accepted","code":202,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Sun, 29 Oct 2023 09:21:22 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"1; mode=block"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"X-Frame-Options","value":"DENY"},{"key":"CF-Cache-Status","value":"DYNAMIC"},{"key":"Report-To","value":"{\"endpoints\":[{\"url\":\"https:\\/\\/a.nel.cloudflare.com\\/report\\/v3?s=r2%2FuLwSilxdD1lpiI1VqpgF0Tu9etiNhupySeBHl0zcU8XV1z8kwR%2FJ00ti4xpMdrTXW%2BkqZkLGrkkaUnMWFsaYlg%2FfA9UC4wIKwmc9LHUwna491EmnC3b3vlabzhUJ11CMpnVmicUE%3D\"}],\"group\":\"cf-nel\",\"max_age\":604800}"},{"key":"NEL","value":"{\"success_fraction\":0,\"report_to\":\"cf-nel\",\"max_age\":604800}"},{"key":"Server","value":"cloudflare"},{"key":"CF-RAY","value":"81da590e8d4345a0-LHR"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"transactionAllowed\": \"YES\"\n}"},{"id":"684201a5-fb5e-4ca3-b429-4860c44d1cec","name":"TrustScoreError","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"requiredinput\": {\r\n \"ip\": \"2001:8004:cc2:fadb:9958:4523:6c42:e3f2\",\r\n \"email\": \"test@gmail.com\",\r\n \"url\": \"http://test.com\"\r\n },\r\n \"optionalInput\": {\r\n \"last_bets\": null,\r\n \"last_wins\": \"\",\r\n \"total_bonuses\": \"\",\r\n \"last_real_bets\": \"\",\r\n \"last_real_wins\": \"\",\r\n \"total_deposits\": \"\",\r\n \"last_bonus_bets\": \"\",\r\n \"last_bonus_wins\": \"\",\r\n \"average_real_bet\": \"\",\r\n \"last_bets_amount\": \"\",\r\n \"last_wins_amount\": \"\",\r\n \"average_bonus_bet\": \"\",\r\n \"bonus_to_deposits\": \"\",\r\n \"last_deposit_date\": \"\",\r\n \"total_withdrawals\": \"\",\r\n \"is_phone_confirmed\": \"\",\r\n \"money_in_money_out\": \"\",\r\n \"last_deposit_amount\": \"\",\r\n \"last_freespins_date\": \"\",\r\n \"last_freespins_name\": \"\",\r\n \"last_free_bonus_date\": \"\",\r\n \"last_free_bonus_name\": \"\",\r\n \"total_bonuses_amount\": \"\",\r\n \"last_freespins_amount\": \"\",\r\n \"last_freespins_status\": \"\",\r\n \"last_real_bets_amount\": \"\",\r\n \"last_real_wins_amount\": \"\",\r\n \"total_deposits_amount\": \"\",\r\n \"last_bonus_bets_amount\": \"\",\r\n \"last_bonus_wins_amount\": \"\",\r\n \"last_free_bonus_amount\": \"\",\r\n \"last_free_bonus_status\": \"\",\r\n \"last_deposit_bonus_date\": \"\",\r\n \"last_deposit_bonus_name\": \"\",\r\n \"last_freespins_currency\": \"\",\r\n \"last_freespins_wagering\": \"\",\r\n \"withdrawals_to_deposits\": \"\",\r\n \"last_free_bonus_currency\": \"\",\r\n \"last_free_bonus_wagering\": \"\",\r\n \"total_withdrawals_amount\": \"\",\r\n \"withdrawal_ewallet_email\": \"\",\r\n \"last_deposit_bonus_amount\": \"\",\r\n \"last_deposit_bonus_status\": \"\",\r\n \"last_deposit_bonus_currency\": \"\",\r\n \"last_deposit_bonus_wagering\": \"\",\r\n \"session\": \"\",\r\n \"payment_mode\": \"\",\r\n \"card_fullname\": \"\",\r\n \"card_bin\": \"\",\r\n \"card_hash\": \"\",\r\n \"card_last\": \"\",\r\n \"card_expire\": \"\",\r\n \"avs_result\": \"\",\r\n \"cvv_result\": \"\",\r\n \"sca_method\": \"\",\r\n \"user_bank_account\": \"\",\r\n \"user_bank_name\": \"\",\r\n \"user_balance\": \"\",\r\n \"user_verification_level\": \"\",\r\n \"status_3d\": \"\",\r\n \"regulation\": \"\",\r\n \"payment_provider\": \"\",\r\n \"phone_number\": \"\",\r\n \"transaction_type\": \"\",\r\n \"transaction_amount\": \"\",\r\n \"transaction_currency\": \"\",\r\n \"merchant_id\": \"\",\r\n \"details_url\": \"\",\r\n \"name\": \"\",\r\n \"person_type\": \"\",\r\n \"gender\": \"\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"{{StagingBaseURL}}/checkTransAllowed"},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Sun, 29 Oct 2023 09:28:33 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"1; mode=block"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"X-Frame-Options","value":"DENY"},{"key":"CF-Cache-Status","value":"DYNAMIC"},{"key":"Report-To","value":"{\"endpoints\":[{\"url\":\"https:\\/\\/a.nel.cloudflare.com\\/report\\/v3?s=herXY1o%2BFZa%2F3qNFjvh4ANgP%2FD0DdAVVFm0vUZDAst2rFkieItm%2Fu0VN24DYrdp7MHMHFKWLvrsBYVIxjDPDaLgJjeGBvlTP2iZoB5EnG1hPPHUVXRNP%2FGMmOTh%2Fp7gsyj0vihW1kMk%3D\"}],\"group\":\"cf-nel\",\"max_age\":604800}"},{"key":"NEL","value":"{\"success_fraction\":0,\"report_to\":\"cf-nel\",\"max_age\":604800}"},{"key":"Server","value":"cloudflare"},{"key":"CF-RAY","value":"81da6398ab144913-LHR"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"Incorrect secret_key\",\n \"code\": \"authentication_failed\"\n}"}],"_postman_id":"bfc94c6f-0b33-4110-b70c-20fd1565bacf"}],"id":"80ab5ea0-979c-44a3-8986-20f3811ac91a","_postman_id":"80ab5ea0-979c-44a3-8986-20f3811ac91a","description":""},{"name":"Cashier APIs","item":[{"name":"Customer","id":"d66a1117-04e3-4ad2-9ec5-5f1283b44a22","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer Token","type":"text"},{"key":"BrandId","value":"brand_id_value","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"fullName\": \"Rahul Agarwal\",\r\n \"emailId\": \"rahul+26@paybomb.tech\",\r\n \"dateOfBirth\": \"1994-06-03\",\r\n \"phoneNo\": \"+91 797639082\",\r\n \"city\": \"Jaipur\",\r\n \"stateCode\": \"RJ\",\r\n \"zipCode\": \"302018\",\r\n \"address\": \"House Number 53, Vaishali Nagar, Jaipur\",\r\n \"country\": \"IN\",\r\n \"merchantCustomerId\": \"rahultestcustomer@paybomb.tech\",\r\n \"CustRegDate\": \"2023-12-27\", //non-mandatory - customer registration date on merchant site\r\n \"SuccessTxn\": \"32\", //non-mandatory - total successful customer orders on merchant site\r\n \"extraParam\": {\r\n \"param1\": \"value1\",\r\n \"param2\": \"value2\",\r\n \"param3\": \"value3\",\r\n \"param4\": \"value4\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.paybomb.net/api/v1/customer","description":"

OVERIEW

The createCustomer API allows merchants to create a customer profile on Paybomb when a user visits their website, facilitating a seamless payment experience by pre-filling the customer's details, on the Paybomb Cashier. The API takes in customer information and returns a unique customerID that can be passed in purchase payload, eliminating the need for customers to manually enter their details during transactions.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Type	Required	Description	Example
merchantCustomerId	String	Yes	unique customer ID provided by merchant. This can be email, mobile or an alphanumeric string	rahultestcustomer@paybomb.tech
fullName	String	Yes	Full name of the customer.	Rahul Agarwal
emailId	String	Yes	Email address of the customer.	test@paybomb.tech
dateOfBirth	String	Optional	Customer's date of birth in YYYY-MM-DD format.	1995-12-27
phoneNo	String	Yes	Customer's phone number. Preferred with the country code	+91 797639082
city	String	Optional	City of the customer.	Jaipur
stateCode	String	Yes	State code of the customer.	RJ
zipCode	String	Optional	Postal code of the customer's location.	302018
address	String	Optional	Full address of the customer.	House Number 53, Vaishali Nagar, Jaipur
country	String	Yes	Country code (ISO 3166-1 alpha-2).	IN
custRegDate	Sting	Optional	Customer registration date on merchant site in YYYY-MM-DD format.	2023-12-27
successTxn	String	Optional	Number of successful transactions customer has carried on merchant site.	32

User Flow

Customer visits merchant's website: The customer selects the product or service and proceeds to checkout page.
\n
Merchant calls the createCustomer API: The merchant sends a POST request to the Paybomb API with the customer's details.
\n
Customer ID generation: Paybomb processes the request and generates a unique customerId which is returned in the response.
\n
Payment Process: The merchant uses the customerId for subsequent session creation, ensuring the customer doesn’t need to re-enter their details for future payments.
\n

Benefits

Seamless user experience: The customer does not have to enter their details manually for every purchase.
\n
Faster Checkout: The merchant can use the customerId for faster payment processing.
\n
Data Security: Customer details are stored securely and can be reused across transactions, reducing the chances of errors.
\n

Implementing createCustomer on merchant site:

The createCustomer can be implemented on merchant site in one of two ways, depending on merchant’s integration flow:

At Checkout:

When a customer initiates the checkout process, your system should invoke the createCustomer API, before actually starting the session.

Call createCustomer: This API call generates a unique customer ID.
\n
Use of Customer ID: Pass the returned customer ID in Session API, when creating a payment session.
\n

Upon Customer Login:

Alternatively, merchants may choose to call createCustomer at the time of customer login on their site.

Persistent Customer Profiles: This approach can help build or maintain a persistent customer profile, ensuring the customer ID is available for any subsequent payment sessions without needing to call createCustomer again.
\n
Integration Flexibility: This is useful for merchants who want to initialize customer data early in the customer journey rather than during checkout.
\n

The method you choose depends on your business requirements and how your system is architected. Regardless of when you call it, the resulting customer ID must be passed to the createSession API to initiate a payment session.

This endpoint makes an HTTP GET request to retrieve customer information from the Paybomb API.

Request

The request does not include any query parameters, but it uses a raw request body with the following parameter \"merchantCustomerId\", which will be the customer id on the merchant's side.

Response

The response of this request can be documented as a JSON schema.

Customer ID	First Name	Last Name	Email	Phone
{{response.customerId}}	{{response.firstName}}	{{response.lastName}}	{{response.email}}	{{response.phone}}

","`;","","function constructVisualizerPayload() {"," return {response: pm.response.json()}","}","","pm.visualizer.set(template, constructVisualizerPayload());"],"type":"text/javascript","packages":{},"requests":{},"id":"8fdb96a5-7280-4a15-be06-fc2459f4071f"}}],"id":"ccd1baa9-8efd-4463-bce0-47b9549f2afa","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"PATCH","header":[{"key":"Authorization","value":"Bearer Token","type":"text"},{"key":"BrandId","value":"brand_id_value","type":"text"},{"key":"Accept","value":"*/*","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"fullName\": \"Gouri Shankar3\",\n \"emailId\": \"gouri@paybomb.techm\",\n \"dateOfBirth\": \"1990-11-27\",\n \"phoneNo\": \"+91 9413666514\",\n \"city\": \"Dausa\",\n \"stateCode\": \"Raj\",\n \"zipCode\": \"202021\",\n \"address\": \"Somnath Nagar\",\n \"country\": \"IN\",\n \"CustRegDate\": \"2023-12-28\",\n \"SuccessTxn\": \"33\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.paybomb.net/api/v1/{PaybombCustomerId}/patchCustomer","description":"

Whenever a customer or the merchant updates customer details on the merchant site, a PATCH request must be made to synchronize these changes with Paybomb.

This API endpoint allows you to update the customer details using an HTTP PATCH request. The request should be sent to https://app.paybomb.tech/api/v1/{customerId}/patchCustomer.

Request Body

The request body should be in raw format and include the following parameters:

fullName (string): The full name of the customer.
\n
emailId (string): The email address of the customer.
\n
dateOfBirth (string): The date of birth of the customer.
\n
phoneNo (string): The phone number of the customer.
\n
city (string): The city of the customer.
\n
stateCode (string): The state code of the customer.
\n
zipCode (string): The zip code of the customer.
\n
address (string): The address of the customer.
\n
country (string): The country of the customer.
\n
createdOn (string): Time when the customer was created.
\n
custRegDate (string): Customer registration date (Non-Mandatory).
\n
successTxn (string): Success transaction details (Non-Mandatory).
\n
lastActivity (string): Time of the last activity.
\n
lastUpdated (string): Time when the last patch was called.
\n
extraParam (object): Additional parameters including param1, param2, param3, param4 with their respective values.
\n

Response

The response will contain the updated customer details or a success message upon successful update.

\n","urlObject":{"protocol":"https","path":["api","v1","{PaybombCustomerId}","patchCustomer"],"host":["api","paybomb","net"],"query":[],"variable":[]}},"response":[{"id":"e02e4246-c372-4b08-add7-70a988e485e1","name":"Success","originalRequest":{"method":"PATCH","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"*/*","type":"text"},{"key":"BrandId","value":"brand_id_value","type":"text"},{"key":"Authorisation","value":"Bearer Token","type":"text"}],"body":{"mode":"raw","raw":"{\n \"fullName\": \"Gouri Shankar3\",\n \"emailId\": \"gouri@paybomb.techm\",\n \"dateOfBirth\": \"1990-11-27\",\n \"phoneNo\": \"+91 9413666514\",\n \"city\": \"Dausa\",\n \"stateCode\": \"Raj\",\n \"zipCode\": \"202021\",\n \"address\": \"Somnath Nagar\",\n \"country\": \"IN\",\n \"CustRegDate\": \"2023-12-28\",\n \"SuccessTxn\": \"33\",\n \"extraParam\": {\n \"param1\": \"value1\",\n \"param2\": \"value2\",\n \"param3\": \"value3\",\n \"param4\": \"value4\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://api.paybomb.net/api/v1/{PaybombCustomerId}/patchCustomer"},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\n \"customerId\": \"691afbc6fd96d34a8113a34d\",\n \"merchantCustomerId\": \"rahultestcustomer1@paybomb.tech\",\n \"fullName\": \"Gouri Shankar3\",\n \"emailId\": \"gouri@paybomb.techm\",\n \"dateOfBirth\": \"1990-11-27\",\n \"phoneNo\": \"+91 9413666514\",\n \"brandID\": \"brandID\",\n \"city\": \"Dausa\",\n \"zipCode\": \"202021\",\n \"address\": \"Somnath Nagar\",\n \"country\": \"IN\",\n \"stateCode\": \"Raj\",\n \"custRegDate\": \"2023-12-28\",\n \"successTrans\": 0,\n \"createdOn\": 1763376070,\n \"lastUpdated\": 1763377024,\n \"lastActivity\": 1763377024,\n \"extraParam\": {\n \"param1\": \"value1\",\n \"param2\": \"value2\",\n \"param3\": \"value3\",\n \"param4\": \"value4\"\n }\n}"}],"_postman_id":"ccd1baa9-8efd-4463-bce0-47b9549f2afa"},{"name":"Purchase Session","id":"0515d8b7-c1c6-4489-81fc-951bbe3b9b89","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer Token","type":"text"},{"key":"BrandId","value":"brand_id_value","type":"text"},{"key":"Accept","value":"*/*","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"customerId\": \"68fed1855ebbe829416b08c6\",\r\n \"merchantRef\": \"rahultestcustomer1@paybomb.tech\", // optional\r\n \"currency\": \"EUR\",\r\n \"products\": [\r\n {\r\n \"name\": \"Product1\",\r\n \"price\": \"10\"\r\n },\r\n {\r\n \"name\": \"Product2\",\r\n \"price\": \"12\"\r\n }\r\n ],\r\n \"totalAmount\": \"22\", // optional, but if present have precedence over sum of prices mentioned above.\r\n \"paymentMethod\": \"VISA\", //optional\r\n \"success_redirect\": \"https://merchant-success-page.com/\",\r\n \"failure_redirect\": \"https://merchant-failure-page.com/\",\r\n \"pending_redirect\": \"https://merchant-pending-page.com/\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\",\r\n \"extraParam\": {\r\n \"param1\": \"value1\",\r\n \"showCryptoConversion\": \"yes\",\r\n \"cryptoCurrencies\": \"[\\\"BTC\\\",\\\"ETH\\\",\\\"USDT\\\",\\\"XRP\\\",\\\"LTC\\\",\\\"DOGE\\\",\\\"ETC\\\",\\\"BNB\\\",\\\"USDC\\\",\\\"SOL\\\",\\\"ADA\\\",\\\"BCH\\\",\\\"DASH\\\",\\\"BTG\\\",\\\"ZEC\\\",\\\"DGB\\\",\\\"EOS\\\",\\\"XLM\\\",\\\"TRX\\\",\\\"QTUM\\\",\\\"POL\\\",\\\"SHIB\\\",\\\"LINK\\\",\\\"DAI\\\",\\\"TON\\\",\\\"AVAX\\\",\\\"FDUSD\\\",\\\"ARB\\\",\\\"OP\\\"]\",\r\n \"param3\": \"value3\",\r\n \"param4\": \"value4\"\r\n }\r\n }","options":{"raw":{"language":"json"}}},"url":"https://api.paybomb.net/api/v1/createSession","description":"

OVERIEW

This API improves the user experience by reducing transaction failures and enhancing the overall payment process, thus reducing transaction churn rates.

Mandatory Parameters

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Type	Description	Example
customerId	String	The unique ID of the customer (generated from createCustomer).	6731a609b6bb5a43ad66c4a6

Show Crypto Conversion

Additionally, there are some default extra parameters that you can pass for allowing Crypto Conversion on Paybomb's cashier itself.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

	Type	Description	Example
extraParam.showCryptoConversion	String	This optional parameter allows customer to see crypto value equivelant to the Fiat amount the customer is planning to pay.	Yes
extraParam.cryptoCurrencies	String	Pass here the allowed crypto tokens on the cashier, where customer can see the the conversion value	[\\\"BTC\\\",\\\"ETH\\\",\\\"USDT\\\",\\\"XRP\\\",\\\"LTC\\\",\\\"DOGE\\\",\\\"ETC\\\",\\\"BNB\\\",\\\"USDC\\\",\\\"SOL\\\",\\\"ADA\\\",\\\"BCH\\\",\\\"DASH\\\",\\\"BTG\\\",\\\"ZEC\\\",\\\"DGB\\\",\\\"EOS\\\",\\\"XLM\\\",\\\"TRX\\\",\\\"QTUM\\\",\\\"POL\\\",\\\"SHIB\\\",\\\"LINK\\\",\\\"DAI\\\",\\\"TON\\\",\\\"AVAX\\\",\\\"FDUSD\\\",\\\"ARB\\\",\\\"OP\\\"]

Usage Flow

Customer completes the createCustomer API: Once the customer is created via the createCustomer API, the merchant proceeds to call the createSession API to generate a session.
\n
Merchant sends createSession request: The merchant sends a POST request to the createSession API with the customer’s customerId and the merchant’s brandId.
\n
Session created automatically on the checkout URL: Paybomb creates the session and associates it with the merchant’s checkout page. This session remains active on the backend, allowing the customer to continue the payment process without interruption.
\n
Customer proceeds to checkout: The customer is redirected to the checkout page as part of the merchant's payment flow, where the session is automatically validated. The session remains active for a set period, allowing the customer to complete the payment without needing to manually interact with the session URL.
\n
Session Expiry: The session expires after the set expiration time (expiryOn), ensuring the payment process is completed within the defined window. Default is 15 mins from the creation time.
\n

Benefits

Seamless Checkout: The session URL is automatically generated and active at the backend, ensuring a smoother and uninterrupted customer experience.
\n
Reduced Transaction Failures: By ensuring the session remains active during the payment process, the chances of transaction failures due to session timeouts are minimized.
\n
Improved User Experience: The customer does not need to click on a session URL or navigate away from the page, leading to faster and more secure payment processing.
\n

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"d2576231-7177-44fd-a34a-5bc0c13671b1","id":"d2576231-7177-44fd-a34a-5bc0c13671b1","name":"Cashier APIs","type":"folder"}},"urlObject":{"protocol":"https","path":["api","v1","createSession"],"host":["api","paybomb","net"],"query":[],"variable":[]}},"response":[{"id":"3b97a6f8-0747-4973-bb11-806b8ca6af5d","name":"Success","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"*/*","type":"text"},{"key":"BrandId","value":"brand_id_value","description":"it is mandatory to pass the BrandId in header for each createSession request. ","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"customerId\": \"68fed1855ebbe829416b08c6\",\r\n \"merchantRef\": \"rahultestcustomer1@paybomb.tech\", // optional\r\n \"currency\": \"EUR\",\r\n \"products\": [\r\n {\r\n \"name\": \"Product1\",\r\n \"price\": \"10\"\r\n },\r\n {\r\n \"name\": \"Product2\",\r\n \"price\": \"12\"\r\n }\r\n ],\r\n \"totalAmount\": \"22\", // optional, but if present have precedence over sum of prices mentioned above.\r\n \"paymentMethod\": \"VISA\", //optional\r\n \"success_redirect\": \"https://merchant-success-page.com/\",\r\n \"failure_redirect\": \"https://merchant-failure-page.com/\",\r\n \"pending_redirect\": \"https://merchant-pending-page.com/\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\",\r\n \"extraParam\": {\r\n \"param1\": \"value1\",\r\n \"param3\": \"value3\",\r\n \"param4\": \"value4\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.paybomb.net/api/v1/createSession"},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"sessionUrl\": \"https://app.paybomb.tech/payment-session/691b02b48c73dd76eedaa379/\",\r\n \"brandId\": \"brand_id_value\",\r\n \"customerId\": \"68fed1855ebbe829416b08c6\",\r\n \"sessionId\": \"691b02b48c73dd76eedaa379\",\r\n \"expiryOn\": 1763378744,\r\n \"createdOn\": 1763377844\r\n}"},{"id":"1c499a73-e28d-46cf-8ed2-8256e5afc8a3","name":"Session with CryptoConversion","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"*/*","type":"text"},{"key":"BrandId","value":"brand_id_value","description":"it is mandatory to pass the BrandId in header for each createSession request. ","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"customerId\": \"68fed1855ebbe829416b08c6\",\r\n \"merchantRef\": \"rahultestcustomer1@paybomb.tech\", // optional\r\n \"currency\": \"EUR\",\r\n \"products\": [\r\n {\r\n \"name\": \"Product1\",\r\n \"price\": \"10\"\r\n },\r\n {\r\n \"name\": \"Product2\",\r\n \"price\": \"12\"\r\n }\r\n ],\r\n \"totalAmount\": \"22\", // optional, but if present have precedence over sum of prices mentioned above.\r\n \"paymentMethod\": \"VISA\", //optional\r\n \"success_redirect\": \"https://merchant-success-page.com/\",\r\n \"failure_redirect\": \"https://merchant-failure-page.com/\",\r\n \"pending_redirect\": \"https://merchant-pending-page.com/\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\",\r\n \"extraParam\": {\r\n \"param1\": \"value1\",\r\n \"showCryptoConversion\": \"yes\",\r\n \"cryptoCurrencies\": \"[\\\"BTC\\\",\\\"ETH\\\",\\\"USDT\\\",\\\"XRP\\\",\\\"LTC\\\",\\\"DOGE\\\",\\\"ETC\\\",\\\"BNB\\\",\\\"USDC\\\",\\\"SOL\\\",\\\"ADA\\\",\\\"BCH\\\",\\\"DASH\\\",\\\"BTG\\\",\\\"ZEC\\\",\\\"DGB\\\",\\\"EOS\\\",\\\"XLM\\\",\\\"TRX\\\",\\\"QTUM\\\",\\\"POL\\\",\\\"SHIB\\\",\\\"LINK\\\",\\\"DAI\\\",\\\"TON\\\",\\\"AVAX\\\",\\\"FDUSD\\\",\\\"ARB\\\",\\\"OP\\\"]\",\r\n \"param3\": \"value3\",\r\n \"param4\": \"value4\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.paybomb.net/api/v1/createSession"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"sessionUrl\": \"https://app.paybomb.tech/payment-session/691b02b48c73dd76eedaa379/\",\n \"brandId\": \"brand_id_value\",\n \"customerId\": \"68fed1855ebbe829416b08c6\",\n \"sessionId\": \"691b02b48c73dd76eedaa379\",\n \"expiryOn\": 1763378744,\n \"createdOn\": 1763377844\n}"},{"id":"70f945eb-3963-44c1-b1e1-cf90772c7c86","name":"Invalid Session","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"*/*","type":"text"},{"key":"BrandId","value":"brand_id_value","description":"it is mandatory to pass the BrandId in header for each createSession request. ","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"customerId\": \"68fed1855ebbe829416b08c6\",\r\n \"merchantRef\": \"rahultestcustomer1@paybomb.tech\", // optional\r\n \"currency\": \"EUR\",\r\n \"products\": [\r\n {\r\n \"name\": \"Product1\",\r\n \"price\": \"10\"\r\n },\r\n {\r\n \"name\": \"Product2\",\r\n \"price\": \"12\"\r\n }\r\n ],\r\n \"totalAmount\": \"22\", // optional, but if present have precedence over sum of prices mentioned above.\r\n \"paymentMethod\": \"VISA\", //optional\r\n \"success_redirect\": \"https://merchant-success-page.com/\",\r\n \"failure_redirect\": \"https://merchant-failure-page.com/\",\r\n \"pending_redirect\": \"https://merchant-pending-page.com/\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\",\r\n \"extraParam\": {\r\n \"param1\": \"value1\",\r\n \"param3\": \"value3\",\r\n \"param4\": \"value4\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.paybomb.net/api/v1/createSession"},"status":"Bad Request","code":400,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"message\": \"Customer does not exist with this Customer Id\",\r\n \"code\": \"Customer Id is invalid\"\r\n}"}],"_postman_id":"0515d8b7-c1c6-4489-81fc-951bbe3b9b89"},{"name":"Payout Session","id":"01de4224-8334-4a7d-a59c-59fb3ef38966","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer Token","type":"text"},{"key":"BrandId","value":"brand_id_value","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"*/*","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"customerId\": \"67c9983fba18400ab6cceb8f\",\r\n \"currency\": \"USD\",\r\n \"products\": [\r\n {\r\n \"name\": \"Product1\",\r\n \"price\": \"2\"\r\n }\r\n ],\r\n \"totalAmount\": \"2\",\r\n \"tax_amount\": \"\", // optional\r\n \"tax_percent\": \"\", // optional\r\n \"type\": \"payout\",\r\n \"success_redirect\": \"https://your.success.redirect.com\",\r\n \"pending_redirect\": \"https://your.pending.redirect.com\",\r\n \"failure_redirect\": \"https://your.failure.redirect.com\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\",\r\n \"extraParam\": {\r\n \"showCryptoConversion\": \"yes\",\r\n \"cryptoCurrencies\": \"[\\\"BTC\\\",\\\"ETH\\\",\\\"USDT\\\",\\\"XRP\\\",\\\"LTC\\\",\\\"DOGE\\\",\\\"ETC\\\",\\\"BNB\\\",\\\"USDC\\\",\\\"SOL\\\",\\\"ADA\\\",\\\"BCH\\\",\\\"DASH\\\",\\\"BTG\\\",\\\"ZEC\\\",\\\"DGB\\\",\\\"EOS\\\",\\\"XLM\\\",\\\"TRX\\\",\\\"QTUM\\\",\\\"POL\\\",\\\"SHIB\\\",\\\"LINK\\\",\\\"DAI\\\",\\\"TON\\\",\\\"AVAX\\\",\\\"FDUSD\\\",\\\"ARB\\\",\\\"OP\\\"]\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.paybomb.net/api/v1/createSession","description":"

This API is used to initiate a payout session for a customer. By passing the customerId (generated via the createCustomer API) and specifying \"type\": \"payout\", a payout session is started.
A sessionURL is returned in the response, which can be used to redirect the customer to the payout cashier. The customer can then select the payout method, pass required parameters, and the payout will be processed.

Parameters:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Type	Description
customerId	string	The unique ID of the customer for whom the payout session is created. This ID is generated by the `createCustomer` API.
currency	string	The currency of the payout session (e.g., USD).
products	array	A list of products associated with the payout (e.g., name and price).
totalAmount	string	The total payout amount (optional. calculated dynamically if value is not passed).
tax_amount	string	The tax amount to be applied (optional).
tax_percent	string	The tax percentage to be applied (optional).
type	string	Should be set to \"payout\" to initiate a payout session.
success_redirect	string	The URL where the customer will be redirected after a successful payout.
pending_redirect	string	The URL where the customer will be redirected after a pending payout.
failure_redirect	string	The URL where the customer will be redirected after a failed payout attempt.
success_callback	string	The callback URL for successful payout.
failure_callback	string	The callback URL for failed payout.
extraParam	object	Contains additional parameters for the payout session.
extraParam.showCryptoConversion	string	Set to \"yes\" to display cryptocurrency conversion.
extraParam.cryptoCurrencies	string	A list of accepted cryptocurrencies (e.g., BTC, ETH, USDT).

Request Headers:

BrandId: Your unique brand ID (required).
\n
Content-Type: application/json (required).
\n

Response:

The API will return a JSON object containing the sessionURL that can be used to redirect the customer to the payout cashier.

{\n    \"sessionUrl\": \"https://app.paybomb.tech/payoutSession/68341ad35f895955355d5452/\",\n    \"brandId\": \"brand_id_value\",\n    \"customerId\": \"67c9983fba18400ab6cceb8f\",\n    \"sessionId\": \"68341ad35f895955355d5452\",\n    \"expiryOn\": 1748246103,\n    \"createdOn\": 1748245203\n}\n\n

This endpoint retrieves the details of a session identified by the provided session ID.

\n
Note that this API only respond once the SessionURL, received in the response for session API, is clicked.
\n

\n
Once the SessionURL is clicked and the user has selected a payment method and click on \"Pay\" button, a purchase is created on our backend. If you call this API before that, you will get an error.
\n

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"d2576231-7177-44fd-a34a-5bc0c13671b1","id":"d2576231-7177-44fd-a34a-5bc0c13671b1","name":"Cashier APIs","type":"folder"}},"urlObject":{"protocol":"https","path":["api","v1","purchases","{Session ID}",""],"host":["api","paybomb","net"],"query":[],"variable":[]}},"response":[{"id":"64d16c44-3e5b-49d1-811a-4d90a8c6b256","name":"202 Success","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer Token"}],"url":"https://api.paybomb.net/api/v1/purchases/6950e4ba5205280b71ac2010/"},"status":"Accepted","code":202,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Sun, 28 Dec 2025 08:03:36 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"X-Frame-Options","value":"ALLOW-FROM *"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"x-session-id","value":"d5308b2a-537d-466a-8273-f754ba3491b8"},{"key":"Vary","value":"Origin"},{"key":"Vary","value":"Access-Control-Request-Method"},{"key":"Vary","value":"Access-Control-Request-Headers"},{"key":"Server","value":"cloudflare"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"0"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"Strict-Transport-Security","value":"max-age=31536000 ; includeSubDomains"},{"key":"X-Cache","value":"Error from cloudfront"},{"key":"Via","value":"1.1 f89daa99b6a349030b23247a4977cb5e.cloudfront.net (CloudFront)"},{"key":"X-Amz-Cf-Pop","value":"IAD61-P10"},{"key":"X-Amz-Cf-Id","value":"Ed-N_b__1xPz7yrAt9mMc6JrgiZqMiuPi3uJbZ4AeuUKm-Ziiohlcw=="},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=V90OEeQkl%2Fh028giW2T2qMbuNADZ5EvKMZG33harMVuXpmo%2BnNQm5JeDtH2802Oa8hw5kJG737sqfdiLVuvIq%2F5E5tHoRdK8Zj6OU6yO255A\"}]}"},{"key":"CF-RAY","value":"9b4f8ac7caf2f4ca-IAD"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"purchaseId\": \"6950e4e3e4a1b008c2fae5c3\",\n \"client\": {\n \"customerId\": \"69034a5a61b460084d20c23b\",\n \"email\": \"rahul+23@paybomb.tech\",\n \"phone\": \"+919634088561\",\n \"full_name\": \"Rahul Agarwal\",\n \"street_address\": \"Vaishali Jaipur\",\n \"country\": \"NA\",\n \"city\": \"jaipur\",\n \"zip_code\": \"202020\",\n \"cc\": [],\n \"bcc\": [],\n \"stateCode\": \"RA\"\n },\n \"updated_on\": 1766909180,\n \"type\": \"purchase\",\n \"paymentMethod\": \"MASTER,VISA,JCB,AMEX,CRYPTO-BRIDGE,FawryPay,INTERAC-E-TRANSFER,INTERAC-REQUEST-MONEY,MOBILEMONEY,NEOSURF,PAYID,PIX,SPEI,THIRDPARTY-UPI,DISCOVER,BANKTRANSFER,VIRTUAL-IBAN,UPI-COLLECT,UPI-QR,VIRTUAL-ACCOUNT,DINERS,NETBANKING,THIRDPARTY-NETBANKING,MAYA,GCASH,INTERAC-EXPRESS,QRPH\",\n \"amountUnit\": \"MAJOR\",\n \"errorMsg\": \"This customer can not be processed !\",\n \"errorCode\": \"NA\",\n \"savedCardUsed\": \"NO\",\n \"redirectType\": \"POST\",\n \"force_recurring\": false,\n \"created_on\": 1766909155,\n \"merchantRef\": \"6950e4e3e4a1b008c2fae5c3\",\n \"merchantName\": \"rahul_test\",\n \"merchantType\": \"MERCHANT\",\n \"purchase\": {\n \"currency\": \"EUR\",\n \"products\": [\n {\n \"name\": \"NA\",\n \"quantity\": 1.0,\n \"price\": 22.0,\n \"discount\": 0,\n \"tax_percent\": \"0.00\"\n }\n ],\n \"total\": 22.0,\n \"requestAmount\": 22.0,\n \"language\": \"en\",\n \"notes\": \"\",\n \"debt\": 0,\n \"total_formatted\": 1.0,\n \"taxAmount\": 0.0,\n \"taxPercent\": 0.0,\n \"request_client_details\": [],\n \"email_message\": \"\"\n },\n \"issuer_details\": {\n \"website\": \"\",\n \"legal_street_address\": \"\",\n \"legal_country\": \"\",\n \"legal_city\": \"\",\n \"legal_zip_code\": \"\",\n \"bank_accounts\": [\n {}\n ],\n \"legal_name\": \"Testing\",\n \"brand_name\": \"Testing\",\n \"registration_number\": \"\",\n \"tax_number\": \"\"\n },\n \"transaction_data\": {\n \"payment_method\": \"\",\n \"flow\": \"payform\",\n \"extra\": {\n \"expiry_month\": \"07\",\n \"amount\": 22.0,\n \"card_issuer\": \"CIAGROUP\",\n \"masked_pan\": \"55555555****4444\",\n \"card_brand\": \"MASTER\",\n \"card_issuer_country\": \"BR\",\n \"card_type\": \"DEBIT\",\n \"cardholder_name\": \"rahul\",\n \"expiry_year\": \"30\"\n },\n \"country\": \"\",\n \"attempts\": [\n {\n \"client_ip\": \"183.83.53.214\",\n \"type\": \"execute\",\n \"payment_method\": \"MASTER\",\n \"flow\": \"payform\",\n \"successful\": false,\n \"country\": \"BR\",\n \"processing_time\": 1766909179,\n \"extra\": {\n \"expiry_month\": \"07\",\n \"amount\": 22.0,\n \"card_issuer\": \"CIAGROUP\",\n \"masked_pan\": \"55555555****4444\",\n \"card_brand\": \"MASTER\",\n \"card_issuer_country\": \"BR\",\n \"card_type\": \"DEBIT\",\n \"cardholder_name\": \"rahul\",\n \"expiry_year\": \"30\"\n },\n \"error\": {\n \"message\": \"This customer can not be processed !\",\n \"code\": \"no_mid_found\"\n }\n }\n ]\n },\n \"status\": \"ERROR\",\n \"status_history\": [\n {\n \"status\": \"created\",\n \"timestamp\": 1766909155\n },\n {\n \"status\": \"pending_execute\",\n \"timestamp\": 1766909179\n },\n {\n \"status\": \"error\",\n \"timestamp\": 1766909180\n },\n {\n \"status\": \"viewed\",\n \"timestamp\": 1766909186\n }\n ],\n \"viewedOn\": 1766909186,\n \"is_test\": false,\n \"brand_id\": \"59c5ed48-caf9-464a-ba54-26e1e02bc1bc\",\n \"send_receipt\": false,\n \"is_recurring_token\": false,\n \"skip_capture\": false,\n \"reference_generated\": \"PS334\",\n \"issued\": \"2025-12-28\",\n \"due\": 1766909155,\n \"refund_upto\": 0,\n \"cc_descriptor\": \"\",\n \"fraudScore\": \"0\",\n \"trustScore\": \"0\",\n \"extraFee\": \"0\",\n \"paidOn\": 0,\n \"receivedAmt\": 0.0,\n \"taxAmount\": 0.0,\n \"surcharge\": 0.0,\n \"surchargeType\": \"\",\n \"sessionId\": \"6950e4ba5205280b71ac2010\",\n \"refund_availability\": \"NONE\",\n \"refundable_amount\": 0.0,\n \"success_redirect\": \"https://google.com/\",\n \"failure_redirect\": \"https://google.com/\",\n \"pending_redirect\": \"https://google.com/\",\n \"cancel_redirect\": \"\",\n \"success_callback\": \"https://your.success.callback.com\",\n \"failure_callback\": \"https://your.failure.callback.com\",\n \"platform\": \"API\",\n \"checkout_url\": \"https://api.choicepay.ca/payments/adb6e07f74ec6197ef764909736d478e/\",\n \"direct_post_url\": \"https://api.choicepay.ca/api/v1/p/6950e4e3e4a1b008c2fae5c3/\",\n \"payoutProcess\": false\n}"},{"id":"81dc2d08-0476-42d5-8e93-c6b6b00440de","name":"400 Bad Request","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer Token"}],"url":"https://api.paybomb.net/api/v1/purchases/6950e4ba5205280b71ac2010/"},"status":"Bad Request","code":400,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Sun, 28 Dec 2025 08:03:36 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"X-Frame-Options","value":"ALLOW-FROM *"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"x-session-id","value":"d5308b2a-537d-466a-8273-f754ba3491b8"},{"key":"Vary","value":"Origin"},{"key":"Vary","value":"Access-Control-Request-Method"},{"key":"Vary","value":"Access-Control-Request-Headers"},{"key":"Server","value":"cloudflare"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"0"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"Strict-Transport-Security","value":"max-age=31536000 ; includeSubDomains"},{"key":"X-Cache","value":"Error from cloudfront"},{"key":"Via","value":"1.1 f89daa99b6a349030b23247a4977cb5e.cloudfront.net (CloudFront)"},{"key":"X-Amz-Cf-Pop","value":"IAD61-P10"},{"key":"X-Amz-Cf-Id","value":"Ed-N_b__1xPz7yrAt9mMc6JrgiZqMiuPi3uJbZ4AeuUKm-Ziiohlcw=="},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=V90OEeQkl%2Fh028giW2T2qMbuNADZ5EvKMZG33harMVuXpmo%2BnNQm5JeDtH2802Oa8hw5kJG737sqfdiLVuvIq%2F5E5tHoRdK8Zj6OU6yO255A\"}]}"},{"key":"CF-RAY","value":"9b4f8ac7caf2f4ca-IAD"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"message\": \"PurchaseId Not found.\",\n \"code\": \"transaction_error\"\n}"},{"id":"386c56a6-3528-439d-9ecc-37c20ac2b289","name":"401 Unauthorized","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer Token"}],"url":"https://api.paybomb.net/api/v1/purchases/{Session ID}/"},"status":"Unauthorized","code":401,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Sun, 28 Dec 2025 08:03:36 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"X-Frame-Options","value":"ALLOW-FROM *"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"x-session-id","value":"d5308b2a-537d-466a-8273-f754ba3491b8"},{"key":"Vary","value":"Origin"},{"key":"Vary","value":"Access-Control-Request-Method"},{"key":"Vary","value":"Access-Control-Request-Headers"},{"key":"Server","value":"cloudflare"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"0"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"Strict-Transport-Security","value":"max-age=31536000 ; includeSubDomains"},{"key":"X-Cache","value":"Error from cloudfront"},{"key":"Via","value":"1.1 f89daa99b6a349030b23247a4977cb5e.cloudfront.net (CloudFront)"},{"key":"X-Amz-Cf-Pop","value":"IAD61-P10"},{"key":"X-Amz-Cf-Id","value":"Ed-N_b__1xPz7yrAt9mMc6JrgiZqMiuPi3uJbZ4AeuUKm-Ziiohlcw=="},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=V90OEeQkl%2Fh028giW2T2qMbuNADZ5EvKMZG33harMVuXpmo%2BnNQm5JeDtH2802Oa8hw5kJG737sqfdiLVuvIq%2F5E5tHoRdK8Zj6OU6yO255A\"}]}"},{"key":"CF-RAY","value":"9b4f8ac7caf2f4ca-IAD"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"Incorrect secret_key\",\n \"code\": \"authentication_failed\"\n}"}],"_postman_id":"2fa57371-d2a6-4b76-bd40-187460c96ed6"},{"name":"Check Status - Payout","id":"254ea1db-3274-4f09-b42d-95e82c4fc32d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer Token","type":"text"}],"url":"https://app.paybomb.tech/api/v1/getpayout/{Session ID}/","description":"

This API tells you about all the details of a Payout, including its history

Mandatory

you need to pass the payoutId or session id in the API URL

Possible Value of Status

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Notes
paid	Transaction Successful
payout_in_process	payout is under Processing.
error	Transaction has Failed.

","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"d2576231-7177-44fd-a34a-5bc0c13671b1","id":"d2576231-7177-44fd-a34a-5bc0c13671b1","name":"Cashier APIs","type":"folder"}},"urlObject":{"path":["getpayout","{Session ID}",""],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"61a47461-520a-42d7-a45b-3921ee5494b5","name":"Success","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer Token","type":"text"}],"url":"https://app.paybomb.tech/api/v1/getpayout/{Session ID}/"},"status":"Accepted","code":202,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Mon, 27 Apr 2026 07:03:52 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"X-Frame-Options","value":"ALLOW-FROM *"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"x-session-id","value":"9be65213-e200-4ef2-831c-683022389e8b"},{"key":"Vary","value":"Origin"},{"key":"Vary","value":"Access-Control-Request-Method"},{"key":"Vary","value":"Access-Control-Request-Headers"},{"key":"Server","value":"cloudflare"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"0"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"Strict-Transport-Security","value":"max-age=31536000 ; includeSubDomains"},{"key":"X-Cache","value":"Error from cloudfront"},{"key":"Via","value":"1.1 ea9784182c7536f5ce15ec71cf0089d6.cloudfront.net (CloudFront)"},{"key":"X-Amz-Cf-Pop","value":"IAD61-P10"},{"key":"X-Amz-Cf-Id","value":"SQqBgIYJCqc_HzF2NrYyoiCCGUdxGyPFZ3OzmUrrL-XBe56tKWTifA=="},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=dRx0V9WF8UC%2FPmYeyh%2Fl2YI7rIhT15NcQDiRVHdKuzF4jjsVyYmbl2imFi%2FSpP4VpmIHsFmO0xzXUjyO1%2BwKeupdremHVjRNwtqENY%2FZxgVpN7KFFzAhSQDhOMdd62Anr2zN\"}]}"},{"key":"CF-RAY","value":"9f2bf84969fa9c85-IAD"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"payoutId\": \"65ffadb4c1c83822903a9205\",\n \"client\": {\n \"email\": \"customer141@email.uk\",\n \"full_name\": \"Test Person-uk\",\n \"street_address\": \"Random city address\",\n \"country\": \"SG\",\n \"city\": \"Singapore\",\n \"zip_code\": \"123456\",\n \"stateCode\": \"test\"\n },\n \"updated_on\": 1711254964,\n \"payoutMethod\": \"Payout-BANKTRANSFER\",\n \"beneficiaryDetail\":{\n \"bankName\": \"DBS Bank\", \n \"bankAccountName\": \"test test\",\n \"bankAccountCurrency\": \"SGD\",\n \"bankAccountNumber\": \"12345640\",\n \"bankCountryCode\" : \"SG\",\n \"swiftCode\": \"DBSSSGSG\",\n \"routing_param\" :\n {\n \"bankCode\": \"897678\",\n \"bankBranchCode\" : \"888\"\n \n }\n },\n \"amountUnit\": \"MAJOR\",\n \"amount\": 1000.0,\n \"errorMsg\": \"Currency Account has insufficient balance.\",\n \"purpose\": \"test payout\",\n \"created_on\": 1711254972,\n \"merchantRef\": \"65ffadb4c1c83822903a9205\",\n \"status\": \"ERROR\",\n \"status_history\": [\n {\n \"status\": \"created\",\n \"timestamp\": 1711254964\n },\n {\n \"status\": \"error\",\n \"timestamp\": 1711254972\n }\n ],\n \"currency\": \"USD\",\n \"success_callback\": \"https://success.com\",\n \"failure_callback\": \"https://failure.com\"\n}"}],"_postman_id":"254ea1db-3274-4f09-b42d-95e82c4fc32d"}],"id":"d2576231-7177-44fd-a34a-5bc0c13671b1","description":"

Paybomb Cashier is a unified payment management solution that connects with leading PSP and acquirers, offering merchants one convenient access point to simplify transaction processing and enhance efficiency.

To start the cashier system, a payment session is initiated—a secure, temporary environment generated by our payment gateway. This session encapsulates all transaction details and state information before the cashier loads, overseeing the complete lifecycle of a payment attempt—from initial setup to final completion—ensuring every necessary detail is managed safely and consistently.

User Defined Fields (also referred to as Merchant Defined Parameters) allow you to attach custom identifiers to transactions. These identifiers can help you map transactions to your internal systems and configure advanced routing rules.

Once created, you can pass the parameter in the purchases or session API using the extraParam object in the payload, to receive the same in the API response and the following webhooks.

Adding a User Defined Field

Click Add Parameters.
\n
Enter the Parameter Name.
\n
Choose the Value Type (Numeric, String, or Boolean).
\n
Click Add to save.
\n

Here is how you can define UDFs in Paybomb's app.

\n\n

Using UDF in API Requests

Once created, you can pass the parameter in the purchases or session API using the extraParam object in the payload, to receive the same in the API response and the following webhooks.

\"extraParam\": {\n    \"userDefinedParameter\": \"value\"\n}\n\n

Best Practices

Use consistent naming conventions for parameters to avoid confusion across integrations.
\n
Keep the number of UDFs minimal — only add fields that provide clear value (e.g., customer segment, order type, risk score).
\n
Leverage UDFs in rule-based routing to optimize processing flows (e.g., route high-value transactions to a specific MID).
\n
Document your UDFs internally so operations and support teams can easily reference them.
\n

Note:
This feature is enabled only for the whitelabel merchant solution. If you are using a merchant solution, please contact your Account Manager for doing these changes.

For cases where the Merchant handles the scheduling:

\n\n

For cases where Paybomb handles the scheduling:

","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"4b29f57d-c248-4e52-bc52-ef28a95c45b7"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"d3057b61-b129-40b2-b030-6e02c1ce0c81"}}],"_postman_id":"489161d7-5e54-4afe-a67c-17e2669ef7f3"},{"name":"APIs","item":[{"name":"Create Customer","id":"c7568edf-b1ed-4679-b30f-e7a2800aa646","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer Token","type":"text"},{"key":"BrandId","value":"brand_id_value","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"fullName\": \"Rahul Agarwal\",\n \"emailId\": \"rahul+26@paybomb.tech\",\n \"dateOfBirth\": \"1994-06-03\",\n \"phoneNo\": \"+91 797639082\",\n \"city\": \"Jaipur\",\n \"stateCode\": \"RJ\",\n \"zipCode\": \"302018\",\n \"address\": \"House Number 53, Vaishali Nagar, Jaipur\",\n \"country\": \"IN\",\n \"merchantCustomerId\": \"rahultestcustomer@paybomb.tech\",\n \"CustRegDate\": \"2023-12-27\", //non-mandatory - customer registration date on merchant site\n \"SuccessTxn\": \"32\", //non-mandatory - total successful customer orders on merchant site\n \"extraParam\": {\n \"param1\": \"value1\",\n \"param2\": \"value2\",\n \"param3\": \"value3\",\n \"param4\": \"value4\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/customer","description":"

OVERIEW

The API takes in customer information and returns a unique customerID that can be passed in purchase payload, eliminating the need for customers to manually enter their details during transactions.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Type	Required	Description	Example
merchantCustomerId	String	Yes	unique customer ID provided by merchant. This can be email, mobile or an alphanumeric string	rahultestcustomer@paybomb.tech
fullName	String	Yes	Full name of the customer.	Rahul Agarwal
emailId	String	Yes	Email address of the customer.	test@paybomb.tech
dateOfBirth	String	Optional	Customer's date of birth in YYYY-MM-DD format.	1995-12-27
phoneNo	String	Yes	Customer's phone number. Preferred with the country code	+91 797639082
city	String	Optional	City of the customer.	Jaipur
stateCode	String	Yes	State code of the customer.	RJ
zipCode	String	Optional	Postal code of the customer's location.	302018
address	String	Optional	Full address of the customer.	House Number 53, Vaishali Nagar, Jaipur
country	String	Yes	Country code (ISO 3166-1 alpha-2).	IN
custRegDate	Sting	Optional	Customer registration date on merchant site in YYYY-MM-DD format.	2023-12-27
successTxn	String	Optional	Number of successful transactions customer has carried on merchant site.	32

User Flow

Customer visits merchant's website: The customer selects the product or service and proceeds to checkout page.
\n
Merchant calls the createCustomer API: The merchant sends a POST request to the Paybomb API with the customer's details.
\n
Customer ID generation: Paybomb processes the request and generates a unique customerId which is returned in the response.
\n
Payment Process: The merchant uses the customerId for subsequent session creation, ensuring the customer doesn’t need to re-enter their details for future payments.
\n

Benefits

Seamless user experience: The customer does not have to enter their details manually for every purchase.
\n
Faster Checkout: The merchant can use the customerId for faster payment processing.
\n
Data Security: Customer details are stored securely and can be reused across transactions, reducing the chances of errors.
\n

Implementing createCustomer on merchant site:

The createCustomer can be implemented on merchant site in one of two ways, depending on merchant’s integration flow:

At Checkout:

When a customer initiates the checkout process, your system should invoke the createCustomer API, before actually starting the session.

Call createCustomer: This API call generates a unique customer ID.
\n
Use of Customer ID: Pass the returned customer ID in Session API, when creating a payment session.
\n

Upon Customer Login:

Alternatively, merchants may choose to call createCustomer at the time of customer login on their site.

Persistent Customer Profiles: This approach can help build or maintain a persistent customer profile, ensuring the customer ID is available for any subsequent payment sessions without needing to call createCustomer again.
\n
Integration Flexibility: This is useful for merchants who want to initialize customer data early in the customer journey rather than during checkout.
\n

This endpoint makes an HTTP GET request to retrieve customer information from the Paybomb API.

Request

The request does not include any query parameters, but it uses a raw request body with the following parameter \"merchantCustomerId\", which will be the customer id on the merchant's side.

Response

The response of this request can be documented as a JSON schema.

OVERIEW

This API improves the user experience by reducing transaction failures and enhancing the overall payment process, thus reducing transaction churn rates.

Mandatory Parameters

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Type	Description	Example
customerId	String	The unique ID of the customer (generated from createCustomer).	6731a609b6bb5a43ad66c4a6

To register a mandate, pass mandate related parameters in the Create Session API to create a mandate registration purchase. Post transaction completion, use Get Status API and Webhooks to capture mandate registration details.

Additional parameters for this usecase:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Notes
payment_type	Mandatory. To be passed as \"mandate\".
mandate	Mandatory. This object is mandatory for mandate flow
mandate.mandate_max_amount	Optional Maximum amount for a mandate.
mandate.amount_variability	Optional Specifies whether the amount is fixed or variable for each recurrence. Possible values: Fixed or Variable
mandate.start_date	Mandatory Specifies the time when the mandate will start.
mandate.end_date	Mandatory Specifies the time when the mandate will end.
mandate.frequency	Mandatory Defines the frequency of mandate execution, how often a customer should be charged. Possible Values: ONETIME: This is for a one-time mandate. The customer provides authorisation to debit their account a single time for a specific amount. DAILY: Recurring mandate. The customer provides authorisation to debit their account daily for a specific amount. WEEKLY: Recurring mandate. Authorisation given by a customer to debit their account weekly once for a specified amount. FORTNIGHTLY: Recurring mandate. The customer provides authorisation to debit their account fortnightly for a specific amount. MONTHLY: Recurring mandate. The customer provides authorisation to debit their account monthly for a specific amount. BIMONTHLY: Recurring mandate. The customer provides authorisation to debit their account bimonthly for a specific amount. QUARTERLY: Recurring mandate. The customer provides authorisation to debit their account quarterly for a specific amount. HALFYEARLY: Recurring mandate. The customer provides authorisation to debit their account once in every 6 months for a specific amount. YEARLY: Recurring mandate. The customer provides authorisation to debit their account once a year for a specific amount. ASPRESENTED: For cases where the scheduling is handled by the merchant. The customer provides authorization to debit their account whenever there is an execution request.
mandate.rule	Optional. Indicates the recurrence rule of the mandate. This rule is not required for onetime, daily, and aspresented recurrence patterns. Possible values: on/before/after By Default: on
mandate.value	Conditional. The recurrence Value of the mandate. It is not required for ONETIME, DAILY and ASPRESENTED frequencies. Possible values: For WEEKLY: The value should be 1-Monday to 7-Sunday. For MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY or YEARLY: The value should be between 1 to 30/31 days. By Default: The value will be treated as 1.

Usage Flow

Customer completes the createCustomer API: Once the customer is created via the createCustomer API, the merchant proceeds to call the createSession API to generate a session.
\n
Merchant sends createSession request: The merchant sends a POST request to the createSession API with the customer’s customerId and the merchant’s brandId.
\n
Session created automatically on the checkout URL: Paybomb creates the session and associates it with the merchant’s checkout page. This session remains active on the backend, allowing the customer to continue the payment process without interruption.
\n
Customer proceeds to checkout: The customer is redirected to the checkout page as part of the merchant's payment flow, where the session is automatically validated. The session remains active for a set period, allowing the customer to complete the payment without needing to manually interact with the session URL.
\n
Session Expiry: The session expires after the set expiration time (expiryOn), ensuring the payment process is completed within the defined window. Default is 15 mins from the creation time.
\n

Benefits

Seamless Checkout: The session URL is automatically generated and active at the backend, ensuring a smoother and uninterrupted customer experience.
\n
Reduced Transaction Failures: By ensuring the session remains active during the payment process, the chances of transaction failures due to session timeouts are minimized.
\n
Improved User Experience: The customer does not need to click on a session URL or navigate away from the page, leading to faster and more secure payment processing.
\n

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"a1593e51-d80d-40c4-9c2c-31943fe87354","id":"a1593e51-d80d-40c4-9c2c-31943fe87354","name":"Recurring Payments","type":"folder"}},"urlObject":{"protocol":"https","path":["api","v1","createSession"],"host":["api","paybomb","net"],"query":[],"variable":[]}},"response":[{"id":"f9827bf3-6740-4bfd-b528-873c5e31c32a","name":"Success","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Bearer Token","type":"text"},{"key":"BrandId","value":"brand_id_value","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"customerId\": \"685f870cf3435a2d5b35ee08\", // mandatory\n \"currency\": \"EUR\",\n \"products\": [\n {\n \"name\": \"Product1\",\n \"price\": \"10\"\n },\n {\n \"name\": \"Product2\",\n \"price\": \"10\"\n }\n ],\n \"totalAmount\": \"21\", // optional, but if present have precedence over sum of prices.\n \"paymentMethod\": \"VISA\", //optional\n \"success_redirect\": \"https://merchant.com/success\",\n \"pending_redirect\": \"https://merchant.com/pending\",\n \"failure_redirect\": \"https://merchant.com/failure\",\n \"success_callback\": \"https://merchant.com/webhook/success\",\n \"failure_callback\": \"https://merchant.com/webhook/failure\",\n \"payment_type\": \"mandate\",\n \"mandate\": {\n \"mandate_max_amount\": \"5000\", // the mandated amount should be less than or equal to this amount.\n \"amount_variability\": \"Fixed\",\n \"start_date\": \"1598965200\", // epoch timestamp or UNIX timestamp\n \"end_date\": \"1914141600\", // epoch timestamp or UNIX timestamp\n \"frequency\": \"MONTHLY\",\n \"rule\": \"on\",\n \"value\": 1\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://api.paybomb.net/api/v1/createSession"},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Sat, 31 Jan 2026 15:03:03 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"X-Frame-Options","value":"ALLOW-FROM *"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"x-session-id","value":"a1b350a8-3571-4d8d-bc24-d101d22cd00a"},{"key":"Vary","value":"Origin"},{"key":"Vary","value":"Access-Control-Request-Method"},{"key":"Vary","value":"Access-Control-Request-Headers"},{"key":"Server","value":"cloudflare"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"0"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"Strict-Transport-Security","value":"max-age=31536000 ; includeSubDomains"},{"key":"X-Cache","value":"Error from cloudfront"},{"key":"Via","value":"1.1 f50e53e9e947bca4dadaaf68ff4c7ea4.cloudfront.net (CloudFront)"},{"key":"X-Amz-Cf-Pop","value":"IAD61-P10"},{"key":"X-Amz-Cf-Id","value":"PPcszsJpkuNycxcxWExDrgtmzycS3Ty-qSugN-xvzxN5XDNbUuYX4A=="},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=rZYK3Hg4zn%2FCuotFLtqHtD2%2F1oVqT7cNmz67YbXBCtsgOhig8X7SPRj8n%2BH9ifhPdt2TF5yERePKHIScEDWDp3BYw9aY1WM%2FmECM6XWiUQw%3D\"}]}"},{"key":"CF-RAY","value":"9c6a17f2cb21d64b-IAD"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"sessionUrl\": \"https://app.paybomb.tech/api/v1/session/685bdefb9a1a8f16b3c4489c/\",\n \"brandId\": \"\",\n \"customerId\": \"685bdd529a1a8f16b3c445a4\",\n \"sessionId\": \"685cc8515e3af922dd0e8c31\",\n \"expiryOn\": 1750852223,\n \"createdOn\": 1750851323,\n \"expiry_in_mins\": \"86400\"\n}"}],"_postman_id":"adb15c64-4597-42aa-9e37-7f7b6ec6cc96"},{"name":"Create Purchase (CIT)","id":"295339cd-b2b9-4ee9-9d70-dd72abb47656","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer Token","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"client\": {\n \"email\": \"rahul@gmail.com\",\n \"country\": \"GB\",\n \"city\": \"London\",\n \"stateCode\": \"LO\",\n \"street_address\": \"Flat 61 Priory Court Romford RM7 0FY\",\n \"zip_code\": \"234567\",\n \"full_name\": \"Rahul Agarwal\",\n \"phone\": \"+44 07932665877\"\n },\n \"purchase\": {\n \"currency\": \"AED\",\n \"products\": [\n {\n \"name\": \"product name\",\n \"price\": \"1\"\n }\n ]\n },\n \"merchantRef\": \"d9db7ec0-f94c-4a9d-8883-54c19c222d81\", // optional\n \"paymentMethod\": \"MASTER\",\n \"brand_id\": \"59c5ed48-caf9-464a-ba54-26e1e02bc1bc\",\n \"payment_type\": \"mandate\",\n \"mandate\": {\n \"mandate_max_amount\": \"5000\",\n \"amount_variability\": \"Fixed\",\n \"start_date\": \"1598965200\",\n \"end_date\": \"1914141600\",\n \"frequency\": \"MONTHLY\",\n \"rule\": \"on\",\n \"value\": 1\n },\n \"success_redirect\": \"https://merchant.com/success\",\n \"pending_redirect\": \"https://merchant.com/pending\",\n \"failure_redirect\": \"https://merchant.com/failure\",\n \"success_callback\": \"https://merchant.com/webhook/success\",\n \"failure_callback\": \"https://merchant.com/webhook/failure\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.paybomb.net/api/v1/purchases","description":"

OVERIEW

The create Purchase API is designed to initiate a payment for a merchant who doesn't want to use Paybomb's cashier and wants to keep everything S2S.

The merchant doesn't need to create a customer in this case and directly needs to call the purchase API and then call the S2S API after that.

Additional parameters for this usecase:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Notes
payment_type	Mandatory. To be passed as \"mandate\".
paymentMethod	Mandatory. Example: MASTER, VISA
brand_id	Your brand id.
mandate	Mandatory. This object is mandatory for mandate flow
mandate.mandate_max_amount	Optional Maximum amount for a mandate.
mandate.amount_variability	Optional Specifies whether the amount is fixed or variable for each recurrence. Possible values: Fixed or Variable
mandate.start_date	Mandatory Specifies the time when the mandate will start.
mandate.end_date	Mandatory Specifies the time when the mandate will end.
mandate.frequency	Mandatory Defines the frequency of mandate execution, how often a customer should be charged. Possible Values: ONETIME: This is for a one-time mandate. The customer provides authorisation to debit their account a single time for a specific amount. DAILY: Recurring mandate. The customer provides authorisation to debit their account daily for a specific amount. WEEKLY: Recurring mandate. Authorisation given by a customer to debit their account weekly once for a specified amount. FORTNIGHTLY: Recurring mandate. The customer provides authorisation to debit their account fortnightly for a specific amount. MONTHLY: Recurring mandate. The customer provides authorisation to debit their account monthly for a specific amount. BIMONTHLY: Recurring mandate. The customer provides authorisation to debit their account bimonthly for a specific amount. QUARTERLY: Recurring mandate. The customer provides authorisation to debit their account quarterly for a specific amount. HALFYEARLY: Recurring mandate. The customer provides authorisation to debit their account once in every 6 months for a specific amount. YEARLY: Recurring mandate. The customer provides authorisation to debit their account once a year for a specific amount. ASPRESENTED: For cases where the scheduling is handled by the merchant. The customer provides authorization to debit their account whenever there is an execution request.
mandate.rule	Optional. Indicates the recurrence rule of the mandate. This rule is not required for onetime, daily, and aspresented recurrence patterns. Possible values: on/before/after By Default: on
mandate.value	Conditional. The recurrence Value of the mandate. It is not required for ONETIME, DAILY and ASPRESENTED frequencies. Possible values: For WEEKLY: The value should be 1-Monday to 7-Sunday. For MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY or YEARLY: The value should be between 1 to 30/31 days. By Default: The value will be treated as 1.

","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"a1593e51-d80d-40c4-9c2c-31943fe87354","id":"a1593e51-d80d-40c4-9c2c-31943fe87354","name":"Recurring Payments","type":"folder"}},"urlObject":{"protocol":"https","path":["api","v1","purchases"],"host":["api","paybomb","net"],"query":[],"variable":[]}},"response":[{"id":"d7620ad5-dcce-49a2-8cb7-844d1265ac98","name":"Success","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Bearer Token","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"client\": {\n \"email\": \"rahul@gmail.com\",\n \"country\": \"GB\",\n \"city\": \"London\",\n \"stateCode\": \"LO\",\n \"street_address\": \"Flat 61 Priory Court Romford RM7 0FY\",\n \"zip_code\": \"234567\",\n \"full_name\": \"Rahul Agarwal\",\n \"phone\": \"+44 07932665877\"\n },\n \"purchase\": {\n \"currency\": \"AED\",\n \"products\": [\n {\n \"name\": \"product name\",\n \"price\": \"1\"\n }\n ]\n },\n \"merchantRef\": \"d9db7ec0-f94c-4a9d-8883-54c19c222d81\", // optional\n \"paymentMethod\": \"MASTER\",\n \"brand_id\": \"59c5ed48-caf9-464a-ba54-26e1e02bc1bc\",\n \"payment_type\": \"mandate\",\n \"mandate\": {\n \"mandate_max_amount\": \"5000\",\n \"amount_variability\": \"Fixed\",\n \"start_date\": \"1598965200\",\n \"end_date\": \"1914141600\",\n \"frequency\": \"MONTHLY\",\n \"rule\": \"on\",\n \"value\": 1\n },\n \"success_redirect\": \"https://merchant.com/success\",\n \"pending_redirect\": \"https://merchant.com/pending\",\n \"failure_redirect\": \"https://merchant.com/failure\",\n \"success_callback\": \"https://merchant.com/webhook/success\",\n \"failure_callback\": \"https://merchant.com/webhook/failure\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.paybomb.net/api/v1/purchases"},"status":"Unauthorized","code":401,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Mon, 30 Mar 2026 12:23:05 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"X-Frame-Options","value":"ALLOW-FROM *"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"x-session-id","value":"668295f8-5770-4492-8318-01e2d1c09664"},{"key":"Vary","value":"Origin"},{"key":"Vary","value":"Access-Control-Request-Method"},{"key":"Vary","value":"Access-Control-Request-Headers"},{"key":"Server","value":"cloudflare"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"0"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"Strict-Transport-Security","value":"max-age=31536000 ; includeSubDomains"},{"key":"X-Cache","value":"Error from cloudfront"},{"key":"Via","value":"1.1 b4011ac432e4f034161d5cccc8a4ac80.cloudfront.net (CloudFront)"},{"key":"X-Amz-Cf-Pop","value":"IAD61-P10"},{"key":"X-Amz-Cf-Id","value":"46KSjvCpG3Uv-3pzVOVedkJkacP2LZAI0m9ByboJ-rzLxQkfNNycJA=="},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=1p%2FF34n2kiKpiE2WnCntzJPGKU28mcMx4pIFZ9F6UFZqmnoSxQEqZQ44WCu6SsOg5eYfqPqYGdhXxgBbuVLNwP5Xyc2OqoL1lTauqUylCkCPuOXJ1VRrvygGOmX9Yslw6BqJ\"}]}"},{"key":"CF-RAY","value":"9e471560fd16d6d5-IAD"}],"cookie":[],"responseTime":null,"body":"{\n \"purchaseId\": \"6905c387faca6576ebf01528\",\n \"client\": {\n \"customerId\": \"NA\",\n \"email\": \"rahul@gmail.com\",\n \"country\": \"GB\",\n \"city\": \"London\",\n \"stateCode\": \"LO\",\n \"street_address\": \"Flat 61 Priory Court Romford RM7 0FY\",\n \"zip_code\": \"234567\",\n \"full_name\": \"Rahul Agarwal\",\n \"phone\": \"+44 07932665877\"\n \"cc\": [],\n \"bcc\": []\n },\n \"updated_on\": 1761985415,\n \"type\": \"purchase\",\n \"paymentMethod\": \"MASTER\",\n \"amountUnit\": \"MAJOR\",\n \"errorMsg\": \"\",\n \"errorCode\": \"NA\",\n \"redirectType\": \"POST\",\n \"force_recurring\": false,\n \"created_on\": 1761985415,\n \"merchantRef\": \"6905c387faca6576ebf01528\",\n \"merchantName\": \"rahul_test\",\n \"merchantType\": \"MERCHANT\",\n \"purchase\": {\n \"currency\": \"AED\",\n \"products\": [\n {\n \"name\": \"product name\",\n \"quantity\": 1.0,\n \"price\": 1.0,\n \"discount\": 0,\n \"tax_percent\": \"0.00\"\n }\n ],\n \"total\": 1.0,\n \"requestAmount\": 1.0,\n \"language\": \"en\",\n \"notes\": \"\",\n \"debt\": 0,\n \"total_formatted\": 1.0,\n \"taxAmount\": 0.0,\n \"taxPercent\": 0.0,\n \"request_client_details\": [],\n \"email_message\": \"\"\n },\n \"issuer_details\": {\n \"website\": \"\",\n \"legal_street_address\": \"\",\n \"legal_country\": \"\",\n \"legal_city\": \"\",\n \"legal_zip_code\": \"\",\n \"bank_accounts\": [\n {}\n ],\n \"legal_name\": \"Testing\",\n \"brand_name\": \"Testing\",\n \"registration_number\": \"\",\n \"tax_number\": \"\"\n },\n \"transaction_data\": {\n \"payment_method\": \"\",\n \"flow\": \"payform\",\n \"extra\": {},\n \"country\": \"\",\n \"attempts\": []\n },\n \"status\": \"CREATED\",\n \"payment_type\": \"mandate\",\n \"mandate\": {\n \"mandate_id\": \"6905c387faca6576ebf01528\",\n \"status\": \"CREATED\",\n \"amount_variability\": \"Fixed\",\n \"mandate_max_amount\": \"5000\",\n \"start_date\": \"1598965200\",\n \"end_date\": \"1914141600\",\n \"frequency\": \"MONTHLY\",\n \"rule\": \"on\",\n \"value\": 1\n },\n \"status_history\": [\n {\n \"status\": \"created\",\n \"timestamp\": 1761985415\n }\n ],\n \"is_test\": false,\n \"brand_id\": \"59c5ed48-caf9-464a-ba54-26e1e02bc1bc\",\n \"send_receipt\": false,\n \"is_recurring_token\": false,\n \"skip_capture\": false,\n \"reference_generated\": \"PS236\",\n \"issued\": \"2025-11-01\",\n \"due\": 1761985415,\n \"refund_upto\": 0,\n \"cc_descriptor\": \"\",\n \"fraudScore\": \"NA\",\n \"trustScore\": \"NA\",\n \"paidOn\": 0,\n \"receivedAmt\": 0.0,\n \"taxAmount\": 0.0,\n \"surcharge\": 0.0,\n \"surchargeType\": \"\",\n \"sessionId\": \"\",\n \"refund_availability\": \"NONE\",\n \"refundable_amount\": 0.0,\n \"success_redirect\": \"https://merchant.com/success\",\n \"pending_redirect\": \"https://merchant.com/pending\",\n \"failure_redirect\": \"https://merchant.com/failure\",\n \"success_callback\": \"https://merchant.com/webhook/success\",\n \"failure_callback\": \"https://merchant.com/webhook/failure\",\n \"platform\": \"API\",\n \"created_from_ip\": \"183.83.53.16, 172.71.172.187, 130.176.161.204\",\n \"checkout_url\": \"https://api.choicepay.ca/payments/1f1d15ebf4f4adcfce479f6220757e30/\",\n \"direct_post_url\": \"https://api.choicepay.ca/api/v1/p/6905c387faca6576ebf01528/\",\n \"payoutProcess\": false\n}"}],"_postman_id":"295339cd-b2b9-4ee9-9d70-dd72abb47656"},{"name":"S2S API","id":"651f791e-99bb-4390-94a3-bb3d43c5a0fc","protocolProfileBehavior":{"disableUrlEncoding":false,"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"cardholder_name\": \"dk\",\r\n \"card_number\": \"4111111111111111\",\r\n \"expires\": \"10/23\",\r\n \"cvc\": \"345\",\r\n \"remember_card\": \"on\",\r\n \"remote_ip\": \"157.38.242.7\",\r\n \"user_agent\": \"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36\",\r\n \"accept_header\": \"text/html\",\r\n \"language\": \"en-US\",\r\n \"java_enabled\": false,\r\n \"javascript_enabled\": true,\r\n \"color_depth\": 24,\r\n \"utc_offset\": 0,\r\n \"screen_width\": 1920,\r\n \"screen_height\": 1080\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/p/64bff4fff63e36669499e9c8/?s2s=true","description":"

This API would be the 2nd in sequence to call if the call to /purchases/ was successful in step 1. and you want to do the transaction via Server-to-Server mode.

The request body would contain the details of the card that's to be transacted upon.

Mandatory parameters in request body:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Notes
remote_ip	IP address of the customer’s device used for transaction. Helps in fraud checks and risk scoring. Ex- 157.38.242.7
user_agent	Full browser and operating system details captured from HTTP header. EX- Chrome/5.0 (X11; Linux x86_64)
accept_header	Browser’s accepted content types (from HTTP header). Used for validating request origin and device info. EX- text/html

Essential parameters in request body:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Notes
cardholder_name	Name of the cardholder
card_number	The card numbers Must be 10-20 characters.
expires	must be greater than the current month/year.
cvc	3 or 4 digit

Other optional parameters in request body:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Notes
language	Preferred language of the user’s browser . EX - en-US
java_enabled	Indicates if Java is enabled in the browser. Helps PSPs in device profiling. Ex- true/false
javascript_enabled	Indicates if JavaScript is enabled in the client browser. Used for 3DS or risk-based checks. Ex- true
color_depth	Bit depth of the display screen. Ex- 24
utc_offset	Difference in minutes between local time and UTC. Used for location and timezone checks. Ex- 330
screen_width	Width of the device screen in pixels. Used in device profiling. Ex- 1920
screen_height	Height of the device screen in pixels. Ex- 1080

Successful Response

If all the details are correct you'll get a 202 response with staus as Pending

{\n    \"status\": \"pending\",\n    \"callback_url\": \"https://app.paybomb.tech/payment/63bd0bf80fb42a076e8a4dd1/\",\n    \"method\": \"GET\"\n}\n\n

If the response code is 202, after receiving the response body, direct the customer to the callback_url provided in the response.

Errors

If there are any errors then it'll be in the format of :

{\n    \"message\": \"descriptive error message\",\n    \"code\": \"error_code\"\n}\n\n

Please see the Status Code section for further details.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Error Messages
Client Ip could not be matched with Merchant Ip
Invalid Card Information
Card is Blocked
Different Type of key used to create purchase and payment
You charges setting is incomplete .Plese Contact to adminstrartor.
Allowed Attempt for this Transaction has been consumed
Invalid Card Expiry(Valid Format:MM/YY) must be greator than current month/year
Customer profile is Blocked
Customer/Card not allowed for transaction

This endpoint will be used to get all the details of a particular mandate. You can search for a particular mandate id or for a particular session id.

Response parameters:

totalDeductedAmount
This is the total amount which is deducted from the user's account.
\n
recurringMandateIds
This object returns a list of all the MIT transactions done for the respective mandate.
\n
nextMandateDate
This is the date when the next recurring payment will happen.
\n

After the successful Mandate registration, Merchant will receive a mandate_id from Paybomb that should be stored against a customer at their end.

If the merchant handles their own scheduling, then for the subsequent transactions, the merchant is supposed to pass a combination of customer_id and mandate_id to do a debit. This API will perform a transaction with a PSP based on the mandate_id passed in the request.

If Paybomb handles the scheduling for the merchant on their behalf, then this API is not for them. The MIT transactions will be handled by Paybomb from our side.

Note:
Recurring payments should only be done if the mandate registration has been successful and the mandate is ACTIVE.

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"a1593e51-d80d-40c4-9c2c-31943fe87354","id":"a1593e51-d80d-40c4-9c2c-31943fe87354","name":"Recurring Payments","type":"folder"}},"urlObject":{"protocol":"https","path":["api","v1","purchases"],"host":["api","paybomb","net"],"query":[],"variable":[]}},"response":[{"id":"79a05392-0318-43bb-ac4b-ad4fb2dd3322","name":"Success","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Bearer Token","type":"text"},{"key":"Accept","value":"*/*","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"customerId\": \"685f870cf3435a2d5b35ee08\", // mandatory\r\n \"email\": \"abby.aadeniran@gmail.com\",\r\n \"phone\": \"+44 07932665877\",\r\n \"full_name\": \"Navya Jain\",\r\n \"street_address\": \"Flat 61 Priory Court Romford RM7 0FY\",\r\n \"country\": \"GB\",\r\n \"city\": \"London\",\r\n \"zip_code\": \"234567\",\r\n \"stateCode\": \"LO\"\r\n },\r\n \"purchase\": {\r\n \"currency\": \"INR\",\r\n \"products\": [\r\n {\r\n \"name\": \"test\",\r\n \"price\": 100\r\n }\r\n ]\r\n },\r\n \"merchantRef\": \"test12\", // optional\r\n \"brand_id\": \"{{merchant_brand_id}}\",\r\n \"payment_type\": \"recurring\",\r\n \"mandate_id\": \"6905c387faca6576ebf01528\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\"\r\n}"},"url":"https://api.paybomb.net/api/v1/purchases"},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Sun, 01 Feb 2026 07:33:08 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"X-Frame-Options","value":"ALLOW-FROM *"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"x-session-id","value":"37f1854e-59ef-4553-928a-273030e84769"},{"key":"Vary","value":"Origin"},{"key":"Vary","value":"Access-Control-Request-Method"},{"key":"Vary","value":"Access-Control-Request-Headers"},{"key":"Server","value":"cloudflare"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"0"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"Strict-Transport-Security","value":"max-age=31536000 ; includeSubDomains"},{"key":"X-Cache","value":"Error from cloudfront"},{"key":"Via","value":"1.1 adbd5a952eb287ac84e05fd5fd42328e.cloudfront.net (CloudFront)"},{"key":"X-Amz-Cf-Pop","value":"IAD61-P10"},{"key":"X-Amz-Cf-Id","value":"7AJkDib2VzETAS6vS-ZJxKBYVyLrDSEJQl_Tnle4M6l-IWwqo2asaA=="},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=EtWT1DIhR3ebhY8soSvPlHMZW8ROhPoWtuiPSMSlWz3I2qU3notH7b6tEnFIyl%2B6iQZs2wFrTKESZRcMCfuxDwqNPDAccnSfvR5gjUb7kUs%3D\"}]}"},{"key":"CF-RAY","value":"9c6fc2486bdc311a-IAD"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"purchaseId\": \"6905c387faca6576ebf01528\",\n \"client\": {\n \"customerId\": \"NA\",\n \"email\": \"abby.aadeniran@gmail.com\",\n \"phone\": \"+44 07932665877\",\n \"full_name\": \"Navya Jain\",\n \"street_address\": \"Flat 61 Priory Court Romford RM7 0FY\",\n \"country\": \"GB\",\n \"city\": \"London\",\n \"zip_code\": \"234567\",\n \"cc\": [],\n \"bcc\": [],\n \"stateCode\": \"LO\"\n },\n \"updated_on\": 1761985415,\n \"type\": \"purchase\",\n \"paymentMethod\": \"MASTER\",\n \"amountUnit\": \"MAJOR\",\n \"errorMsg\": \"\",\n \"errorCode\": \"NA\",\n \"redirectType\": \"POST\",\n \"force_recurring\": false,\n \"created_on\": 1761985415,\n \"merchantRef\": \"6905c387faca6576ebf01528\",\n \"merchantName\": \"rahul_test\",\n \"merchantType\": \"MERCHANT\",\n \"purchase\": {\n \"currency\": \"GBP\",\n \"products\": [\n {\n \"name\": \"product name\",\n \"quantity\": 1.0,\n \"price\": 10.0,\n \"discount\": 0,\n \"tax_percent\": \"0.00\"\n }\n ],\n \"total\": 1.0,\n \"requestAmount\": 1.0,\n \"language\": \"en\",\n \"notes\": \"\",\n \"debt\": 0,\n \"total_formatted\": 1.0,\n \"taxAmount\": 0.0,\n \"taxPercent\": 0.0,\n \"request_client_details\": [],\n \"email_message\": \"\"\n },\n \"issuer_details\": {\n \"website\": \"\",\n \"legal_street_address\": \"\",\n \"legal_country\": \"\",\n \"legal_city\": \"\",\n \"legal_zip_code\": \"\",\n \"bank_accounts\": [\n {}\n ],\n \"legal_name\": \"Testing\",\n \"brand_name\": \"Testing\",\n \"registration_number\": \"\",\n \"tax_number\": \"\"\n },\n \"transaction_data\": {\n \"payment_method\": \"\",\n \"flow\": \"payform\",\n \"extra\": {},\n \"country\": \"\",\n \"attempts\": []\n },\n \"status\": \"PAID\",\n \"payment_type\": \"recurring\",\n \"mandate\": {\n \"mandate_id\": \"6905c387faca6576ebf01528\",\n \"amount_variability\": \"Fixed\",\n \"status\": \"ACTIVE\",\n \"mandate_max_amount\": \"5000\",\n \"start_date\": \"1598965200\",\n \"end_date\": \"1914141600\",\n \"frequency\": \"ASPRESENTED\",\n \"rule\": \"on\",\n \"value\": 1\n },\n \"mandate_id\": \"6905c387faca6576ebf01528\",\n \"status_history\": [\n {\n \"status\": \"paid\",\n \"timestamp\": 1761985415\n }\n ],\n \"is_test\": false,\n \"brand_id\": \"59c5ed48-caf9-464a-ba54-26e1e02bc1bc\",\n \"send_receipt\": false,\n \"is_recurring_token\": false,\n \"skip_capture\": false,\n \"reference_generated\": \"PS236\",\n \"issued\": \"2025-11-01\",\n \"due\": 1761985415,\n \"refund_upto\": 0,\n \"cc_descriptor\": \"\",\n \"fraudScore\": \"NA\",\n \"trustScore\": \"NA\",\n \"paidOn\": 0,\n \"receivedAmt\": 0.0,\n \"taxAmount\": 0.0,\n \"surcharge\": 0.0,\n \"surchargeType\": \"\",\n \"sessionId\": \"\",\n \"refund_availability\": \"NONE\",\n \"refundable_amount\": 0.0,\n \"success_redirect\": \"https://merchant.com/success\",\n \"pending_redirect\": \"https://merchant.com/pending\",\n \"failure_redirect\": \"https://merchant.com/failure\",\n \"success_callback\": \"https://merchant.com/webhook/success\",\n \"failure_callback\": \"https://merchant.com/webhook/failure\",\n \"platform\": \"API\",\n \"created_from_ip\": \"183.83.53.16, 172.71.172.187, 130.176.161.204\",\n \"checkout_url\": \"https://api.choicepay.ca/payments/1f1d15ebf4f4adcfce479f6220757e30/\",\n \"direct_post_url\": \"https://api.choicepay.ca/api/v1/p/6905c387faca6576ebf01528/\",\n \"payoutProcess\": false\n}"}],"_postman_id":"fe2dfb41-1529-4cb4-b681-28e7348389dc"},{"name":"Revoke Mandate","id":"e28d7d32-629e-41a9-9df7-58ee5eb45f58","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"Brandid","value":"your-brand-id","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"body":{"mode":"raw","raw":"{\n \"mandate_id\": \"685cc8515e3af922dd0e8c31\",\n \"command\": \"revoke\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.paybomb.net/api/v1/mandate","description":"

Required for cases where the Paybomb is handling the scheduling of recurring payments. Use this API to revoke/cancel an ACTIVE mandate.

Note:
Revoking a mandate should be done at the same instance this API is called. The mandate status should be updated to “REVOKED” at the same instant.

Required for cases where the Paybomb is handling the scheduling of recurring payments. Use this API to pause an ACTIVE mandate.

Additional parameters for this usecase:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Notes
command	Mandatory. To be passed as \"pause\".
mandate_id	Mandatory.
pause_start_date	Optional Date in UNIX EPOCH timestamp (UTC timezone) format, when the mandate will be paused. If not passed, Default value will be the current date.
pause_end_date	Mandatory Date in UNIX EPOCH timestamp (UTC timezone) format, when the mandate status will be automatically changed to ACTIVE.

Note:
For pausing a mandate you need to keep the exact timestamp in mind.
If a recurring payment is scheduled between the pause_start_date and pause_end_date then it will not be executed.

This endpoint will be used to list all the mandates for a particular customer of a merchant.

Response parameters:

totalDeductedAmount
This is the total amount which is deducted from the user's account.
\n
recurringMandateIds
This object returns a list of all the MIT transactions done for the respective mandate.
\n
nextMandateDate
This is the date when the next recurring payment will happen.
\n

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"a1593e51-d80d-40c4-9c2c-31943fe87354","id":"a1593e51-d80d-40c4-9c2c-31943fe87354","name":"Recurring Payments","type":"folder"}},"urlObject":{"protocol":"https","path":["api","v1","mandate"],"host":["api","paybomb","net"],"query":[{"key":"customerId","value":"696bd627b0c24568ade4675e"},{"key":"email","value":"test@gmail.com"}],"variable":[]}},"response":[{"id":"71247764-4fb9-4ee1-a00d-92fa6cc72168","name":"Success","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"BrandId","value":"your-brand-id","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"url":{"raw":"https://api.paybomb.net/api/v1/mandate?customerId=696bd627b0c24568ade4675e&email=test@gmail.com","protocol":"https","host":["api","paybomb","net"],"path":["api","v1","mandate"],"query":[{"key":"customerId","value":"696bd627b0c24568ade4675e"},{"key":"email","value":"test@gmail.com"}]}},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Sun, 01 Feb 2026 07:45:33 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"X-Frame-Options","value":"ALLOW-FROM *"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"x-session-id","value":"f16548e2-fc87-44fc-bbf1-767f2c82af0c"},{"key":"Vary","value":"Origin"},{"key":"Vary","value":"Access-Control-Request-Method"},{"key":"Vary","value":"Access-Control-Request-Headers"},{"key":"Server","value":"cloudflare"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"0"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"Strict-Transport-Security","value":"max-age=31536000 ; includeSubDomains"},{"key":"X-Cache","value":"Error from cloudfront"},{"key":"Via","value":"1.1 9bce423254194c16408d5cf7234126e2.cloudfront.net (CloudFront)"},{"key":"X-Amz-Cf-Pop","value":"IAD61-P10"},{"key":"X-Amz-Cf-Id","value":"ywr-KbYLgcl2CP9ZyFndEJjR7VI6jATRNoLeJen1sLm6hmk4VPBSGw=="},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=SuOGk1BmR%2B6RDq9oMjQI0y4v%2B2wZpehSeXuXxwibUF8%2B%2Fg6CIX9K27%2F1oT205007Yq63%2BR2d2casubErbR9yDAk78NgFsX%2Bd%2FGq2v9VBBGY%3D\"}]}"},{"key":"CF-RAY","value":"9c6fd4788b13c5ce-IAD"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"mandates\": [\n {\n \"status\": \"ACTIVE\",\n \"frequency\": \"WEEKLY\",\n \"rule\": \"after\",\n \"value\": 4,\n \"totalDeductedAmount\": \"10.00\",\n \"recurringMandateIds\": [\n \"6973ad04fa54ee2cf14f438c\",\n \"697ce750e6446c7babfe4727\"\n ],\n \"email\": \"test@gmail.com\",\n \"nextMandateDate\": 1770398106,\n \"customer_id\": \"696bd627b0c24568ade4675e\",\n \"mandate_id\": \"696bc39a7bc779fac5201357\",\n \"mandate_max_amount\": 120,\n \"amount_variability\": \"Variable\",\n \"start_date\": \"1768670106\"\n },\n {\n \"status\": \"CREATED\",\n \"frequency\": \"WEEKLY\",\n \"rule\": \"on\",\n \"value\": 6,\n \"totalDeductedAmount\": \"0\",\n \"email\": \"test@gmail.com\",\n \"customer_id\": \"696bd627b0c24568ade4675e\",\n \"mandate_id\": \"696bd627b0c24568ade4675e\",\n \"mandate_max_amount\": 120,\n \"amount_variability\": \"Variable\",\n \"start_date\": \"1768674855\",\n \"session_id\": \"\"\n },\n {\n \"status\": \"ACTIVE\",\n \"frequency\": \"WEEKLY\",\n \"rule\": \"after\",\n \"value\": 4,\n \"totalDeductedAmount\": \"0\",\n \"email\": \"test@gmail.com\",\n \"customer_id\": \"696bd627b0c24568ade4675e\",\n \"mandate_id\": \"69788a5dd1ed27eeb5fb89d6\",\n \"mandate_max_amount\": 120,\n \"amount_variability\": \"Variable\",\n \"start_date\": \"1769507493\",\n \"session_id\": \"\"\n },\n {\n \"status\": \"ACTIVE\",\n \"frequency\": \"WEEKLY\",\n \"rule\": \"after\",\n \"value\": 4,\n \"totalDeductedAmount\": \"1000\",\n \"recurringMandateIds\": [\n \"6973ad04fa54ee2cf14f438c\",\n \"697ce750e6446c7babfe4727\"\n ],\n \"email\": \"test@gmail.com\",\n \"customer_id\": \"696bd627b0c24568ade4675e\",\n \"mandate_id\": \"69788d2f0ea4df4fd4e6eb5b\",\n \"mandate_max_amount\": 120,\n \"amount_variability\": \"Variable\",\n \"start_date\": \"1769508214\",\n \"session_id\": \"\"\n },\n {\n \"status\": \"FAILED\",\n \"frequency\": \"WEEKLY\",\n \"rule\": \"after\",\n \"value\": 4,\n \"totalDeductedAmount\": \"0\",\n \"email\": \"test@gmail.com\",\n \"customer_id\": \"696bd627b0c24568ade4675e\",\n \"mandate_id\": \"697b533b34d180d90cfb2f5f\",\n \"mandate_max_amount\": 120,\n \"amount_variability\": \"Variable\",\n \"start_date\": \"1769689915\",\n \"session_id\": \"\"\n },\n {\n \"status\": \"CREATED\",\n \"frequency\": \"WEEKLY\",\n \"rule\": \"after\",\n \"value\": 4,\n \"totalDeductedAmount\": \"0\",\n \"email\": \"test@gmail.com\",\n \"customer_id\": \"696bd627b0c24568ade4675e\",\n \"mandate_id\": \"697de0e15d2e562bf8b4552a\",\n \"mandate_max_amount\": 120,\n \"amount_variability\": \"Variable\",\n \"start_date\": \"1769857249\",\n \"session_id\": \"\"\n }\n ]\n}"}],"_postman_id":"dd5c1043-06fa-4406-8358-5be4bbe84957"},{"name":"Get Status","id":"c1d5e07a-1b41-42b7-b410-42f3ce95738b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"url":"https://app.paybomb.tech/api/v1/purchases/{purchaseId}/","description":"

This API tells you about all the details of a recurring payment which occurred

Mandatory

you need to pass the PurchaseID in the API URL

Possible Value of Status

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Notes
paid	Transaction Successful
expired	Purchase has Expired.
error	Transaction has Failed.

Response Examples

In the response examples you can see instances of both Paid and Error Status purchases.

Error Details

If there are any issues on the Purchase you can get more details from the transaction_data.attempts.error attribute of the response object

Errors

If there are any errors then it'll be in the format of :

{\n    \"message\": \"descriptive error message\",\n    \"code\": \"error_code\"\n}\n\n

Please see the Status Code section for further details.

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"a1593e51-d80d-40c4-9c2c-31943fe87354","id":"a1593e51-d80d-40c4-9c2c-31943fe87354","name":"Recurring Payments","type":"folder"}},"urlObject":{"path":["purchases","{purchaseId}",""],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"dd7910a1-003e-4fb2-9c8f-b292e93a9047","name":"Success","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"url":"https://app.paybomb.tech/api/v1/purchases/{purchaseId}/"},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Sun, 01 Feb 2026 07:59:35 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"X-Frame-Options","value":"ALLOW-FROM *"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"x-session-id","value":"e222737a-b9e9-4562-94de-5b80b056c180"},{"key":"Vary","value":"Origin"},{"key":"Vary","value":"Access-Control-Request-Method"},{"key":"Vary","value":"Access-Control-Request-Headers"},{"key":"Server","value":"cloudflare"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"0"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"Strict-Transport-Security","value":"max-age=31536000 ; includeSubDomains"},{"key":"X-Cache","value":"Error from cloudfront"},{"key":"Via","value":"1.1 f89daa99b6a349030b23247a4977cb5e.cloudfront.net (CloudFront)"},{"key":"X-Amz-Cf-Pop","value":"IAD61-P10"},{"key":"X-Amz-Cf-Id","value":"eUcDXjdNU1qDjwPQst7oM9Kbi8qYyd8sncr30-6kphukYSEGv-qwUg=="},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=i8qaRQprp0TLqlSo5At%2FjpQANnSZgP8iEeVFnMasIN8xyAN2mdqYXVqP3dXt2AbZRL8fj6SRWa%2BFA1dybSS8ebE5scTH8BsB6Ubx8ppJSxc%3D\"}]}"},{"key":"CF-RAY","value":"9c6fe9092c493ec9-IAD"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"purchaseId\": \"6973ad04fa54ee2cf14f438c\",\n \"client\": {\n \"customerId\": \"NA\",\n \"email\": \"sl68792.bravo@bravapay.com\",\n \"phone\": \"0557719399\",\n \"full_name\": \"Test user\",\n \"date_of_birth\": \"2004-07-12\",\n \"street_address\": \"10 New Burlington StreetApt. 214\",\n \"country\": \"CA\",\n \"city\": \"London\",\n \"zip_code\": \"W1S 3BE\",\n \"cc\": [],\n \"bcc\": [],\n \"tax_number\": \"+447755564318\",\n \"bankAccountNumber\": \"1345789678\",\n \"stateCode\": \"QLD\"\n },\n \"updated_on\": 1769188614,\n \"type\": \"purchase\",\n \"paymentMethod\": \"VISA\",\n \"amountUnit\": \"MAJOR\",\n \"errorMsg\": \"ERROR_PARSING_GROUP_ID\",\n \"errorCode\": \"NA\",\n \"force_recurring\": false,\n \"created_on\": 1769188612,\n \"merchantRef\": \"6973ad04fa54ee2cf14f438c\",\n \"purchase\": {\n \"currency\": \"USD\",\n \"products\": [\n {\n \"name\": \"gaming cards\",\n \"quantity\": 1.0,\n \"price\": 10.0,\n \"discount\": 0,\n \"tax_percent\": \"0.00\"\n }\n ],\n \"total\": 10.0,\n \"requestAmount\": 10.0,\n \"language\": \"en\",\n \"notes\": \"\",\n \"debt\": 0,\n \"total_formatted\": 1.0,\n \"taxAmount\": 0.0,\n \"taxPercent\": 0.0,\n \"request_client_details\": [],\n \"email_message\": \"\"\n },\n \"issuer_details\": {\n \"website\": \"\",\n \"legal_street_address\": \"\",\n \"legal_country\": \"\",\n \"legal_city\": \"\",\n \"legal_zip_code\": \"\",\n \"bank_accounts\": [\n {}\n ],\n \"legal_name\": \"zenith\",\n \"brand_name\": \"zenith\",\n \"registration_number\": \"\",\n \"tax_number\": \"\"\n },\n \"transaction_data\": {\n \"payment_method\": \"\",\n \"flow\": \"payform\",\n \"extra\": {\n \"expiry_month\": \"01\",\n \"amount\": 10.0,\n \"card_issuer\": \"VISION BANK\",\n \"masked_pan\": \"42222222*2222\",\n \"card_brand\": \"VISA\",\n \"card_issuer_country\": \"SA\",\n \"card_type\": \"DEBIT\",\n \"cardholder_name\": \"fgjhknms\",\n \"expiry_year\": \"29\"\n },\n \"country\": \"\",\n \"attempts\": [\n {\n \"client_ip\": \"49.36.232.107\",\n \"type\": \"execute\",\n \"payment_method\": \"VISA\",\n \"flow\": \"payform\",\n \"successful\": false,\n \"country\": \"VISA\",\n \"processing_time\": 1769188612,\n \"extra\": {\n \"amount\": 10.0,\n \"masked_pan\": \"VISA\",\n \"card_brand\": \"VISA\",\n \"card_issuer_country\": \"VISA\",\n \"cardholder_name\": \"Test user\"\n },\n \"error\": {\n \"message\": \"This customer can not be processed !\",\n \"code\": \"transaction_error\"\n }\n },\n {\n \"client_ip\": \"\",\n \"type\": \"execute\",\n \"payment_method\": \"VISA\",\n \"flow\": \"payform\",\n \"successful\": false,\n \"country\": \"SA\",\n \"processing_time\": 1769188613,\n \"extra\": {\n \"expiry_month\": \"01\",\n \"amount\": 10.0,\n \"card_issuer\": \"VISION BANK\",\n \"masked_pan\": \"42222222*2222\",\n \"card_brand\": \"VISA\",\n \"card_issuer_country\": \"SA\",\n \"card_type\": \"DEBIT\",\n \"cardholder_name\": \"fgjhknms\",\n \"expiry_year\": \"29\"\n },\n \"error\": {\n \"message\": \"ERROR_PARSING_GROUP_ID\",\n \"code\": \"transaction_error\"\n }\n }\n ]\n },\n \"status\": \"ERROR\",\n \"status_history\": [\n {\n \"status\": \"created\",\n \"timestamp\": 1769188612\n },\n {\n \"status\": \"pending_execute\",\n \"timestamp\": 1769188612\n },\n {\n \"status\": \"error\",\n \"timestamp\": 1769188613\n },\n {\n \"status\": \"pending_execute\",\n \"timestamp\": 1769188613\n },\n {\n \"status\": \"error\",\n \"timestamp\": 1769188614\n },\n {\n \"status\": \"viewed\",\n \"timestamp\": 1770016552\n }\n ],\n \"viewedOn\": 1770016552,\n \"is_test\": false,\n \"brand_id\": \"555c458b-e737-4905-adb2-2451d37cbb6e\",\n \"send_receipt\": false,\n \"is_recurring_token\": false,\n \"skip_capture\": false,\n \"reference_generated\": \"PS1841\",\n \"issued\": \"2026-01-23\",\n \"due\": 1769188612,\n \"refund_upto\": 0,\n \"cc_descriptor\": \"\",\n \"fraudScore\": \"NA\",\n \"trustScore\": \"NA\",\n \"extraFee\": \"0\",\n \"paidOn\": 0,\n \"receivedAmt\": 0.0,\n \"taxAmount\": 0.0,\n \"surcharge\": 0.0,\n \"surchargeType\": \"\",\n \"sessionId\": \"\",\n \"refund_availability\": \"NONE\",\n \"refundable_amount\": 0.0,\n \"success_redirect\": \"https://app.paybomb.tech/getResponse.jsp?issucces=true\",\n \"failure_redirect\": \"https://app.paybomb.tech/getResponse.jsp?issucces=false\",\n \"pending_redirect\": \"https://app.paybomb.tech/getResponse.jsp?issucces=pending \",\n \"cancel_redirect\": \"\",\n \"success_callback\": \"https://www.google.com/\",\n \"failure_callback\": \"https://app.paybomb.tech/merchant\",\n \"platform\": \"API\",\n \"created_from_ip\": \"49.36.232.107\",\n \"checkout_url\": \"https://test4.paymentsclub.net/payments/a28ed9974a22a4cbd5f2f49cc26cc334/\",\n \"direct_post_url\": \"https://test4.paymentsclub.net/api/v1/p/6973ad04fa54ee2cf14f438c/\",\n \"payoutProcess\": false,\n \"payment_type\": \"internal recurring\",\n \"mandate_id\": \"696bc39a7bc779fac5201357\"\n}"}],"_postman_id":"c1d5e07a-1b41-42b7-b410-42f3ce95738b"}],"id":"3ffa0d69-d121-4818-abe0-4109b19af2af","_postman_id":"3ffa0d69-d121-4818-abe0-4109b19af2af","description":"","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"a1593e51-d80d-40c4-9c2c-31943fe87354","id":"a1593e51-d80d-40c4-9c2c-31943fe87354","name":"Recurring Payments","type":"folder"}}}],"id":"a1593e51-d80d-40c4-9c2c-31943fe87354","description":"

Overview

Recurring Payments allow merchants to automatically charge customers at predefined or flexible intervals without requiring the customer to re-enter payment details each time.

A Mandate represents the customer’s authorization that links their payment method to the merchant for future recurring charges. Once created, this mandate is used as a secure reference for all upcoming payments.

Instead of processing every transaction as a one-time payment, merchants rely on mandates to execute recurring debits in a frictionless and compliant manner.

The recurring payments may be initiated using Paybomb APIs as fixed/ non-fixed intervals based on your business use case.

The Paybomb Subscription module (also known as Mandates) enables merchants to automate recurring billing for products and services. Unlike standard one-off transactions, this feature creates a persistent link between the merchant and the customer's payment method, allowing for future charges without requiring the customer to be present or re-enter their details.

This system is built around two fundamental transaction types that define the lifecycle of a subscription:

1. Mandate Registration (CIT)

The Customer Initiated Transaction (CIT) represents the initial setup of the recurring payment mandate, during which the customer is actively present on the merchant’s website or application (in-session flow).

In this flow, the merchant collects and submits the customer’s basic details along with the mandate configuration, including registration information, payment amount (fixed or variable, as applicable), and the scheduling frequency for recurring debits.

As part of the setup process, the customer must explicitly provide consent for the mandate. To authenticate and activate the mandate, the customer also completes a one-time payment using the selected payment method. Once this payment is successful, the mandate is registered and becomes eligible for future automated recurring transactions as per the defined schedule.

Purpose:

Capture customer payment details
\n
Authenticate the transaction (typically via 3D Secure)
\n
Collect customer consent for recurring billing
\n

Outcome:

A unique mandate_id is generated
\n
This mandate acts as a secure token for all future charges
\n

Use Case:

The customer signs up for a subscription and completes the first payment

2. Recurring Payments (MIT)

The Merchant Initiated Transaction (MIT) represents the execution phase of the recurring payment lifecycle. In this stage, payments are automatically triggered by the merchant’s system or through Paybomb’s built-in scheduler without requiring the customer to be actively present (off-session flow).

Once a mandate is successfully registered, merchants can initiate recurring debits as per the defined schedule and payment terms. These transactions are processed seamlessly using the customer’s authorized payment method.

The Paybomb Mandate module provides the following benefits:

Prebuilt support for a complete mandate registration experience using cards as the payment method
\n
Flexible mandate setup to match different business models and customer requirements
\n
Simplified execution of recurring payments through the Paybomb Dashboard with minimal operational effort
\n
Built-in analytics and reporting tools to monitor mandate sign-ups, payment performance, and renewals
\n

Purpose:

Debit the customer according to the defined schedule or usage

Mechanism:

Merchant (or Paybomb scheduler) sends payment requests using the mandate_id
\n
No card details are required again
\n
Usually bypasses 3D Secure
\n

Use Case:

Monthly subscription renewal payment.

Key Capabilities

Flexible Scheduling: Define rigid schedules (Daily, Weekly, Monthly, Yearly) or use \"As Presented\" for irregular billing intervals.
\n
Amount Variability: Support for Fixed amounts (e.g., $10/month license) or Variable amounts (e.g., utility bills where the cost changes based on usage).
\n
Smart Management:
\n
- Merchant Managed: You track the dates and trigger the API call when payment is due.
  \n
- Paybomb Managed: You define the rules (start date, end date, frequency), and Paybomb handles the execution logic.
  \n
\n
Analytics & Operations: Includes a dedicated dashboard for monitoring signup performance, renewal success rates, and managing cancellations.
\n

There are 2 ways in which subscriptions are handled at Paybomb’s end:

Merchant Managed Scheduling

After successfully registering the mandate, the merchant creates a subscription linked to the customer’s mandate. Based on the defined billing cycle and business logic, the merchant then triggers the Recurring Payments API according to their own payment schedule to execute automated debits.

This approach allows merchants to maintain full control over when and how recurring charges are initiated.

Merchant tracks payment due dates
\n
Merchant triggers recurring API calls manually
\n

Best for:

Custom billing logic or internal scheduling systems.

Paybomb Managed Scheduling

In this model, the merchant creates a subscription within the Paybomb system and submits the recurring payment schedule, including billing frequency and timing. Based on the provided configuration, Paybomb automatically manages the execution of recurring transactions as per the defined schedule.

This removes the need for merchants to manually trigger each payment, ensuring consistent and timely debits while maintaining a fully automated recurring billing process

Merchant defines payment rules (start date, frequency, end date)
\n
Paybomb automatically executes recurring charges
\n

Best for:

Standard subscription models with minimal operational overhead.

Prerequisites

Before starting the mandate integration, merchants must ensure that the required configurations are enabled both at the PSP level and within the Paybomb system.

Mandate Enablement at PSP Level

Merchants must enable mandate-related features on their respective PSP (Payment Service Provider) dashboard. This ensures that the PSP supports recurring and mandate-based transactions.

Configuration on the Paybomb Dashboard

For whitelabel merchants or those using Paybomb’s whitelabel solution, the mandate support toggle must be enabled within the MID settings of the PSP configuration. This allows Paybomb to recognize and route mandate transactions correctly.
\n
For merchants directly onboarded with Paybomb, this configuration is managed by the Paybomb team. Merchants should coordinate with their account manager to ensure mandate enablement is completed.
\n

Fetches a paginated list of transactions. This endpoint is optimized for high-volume retrieval and returns a summary view of each transaction (ID and Status).

Important Path Params to consider:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Fields	Description
page_no	The index number of the page to retrieve. Zero-based indexing: The first page is 0, the second is 1, etc. Example: To get the third page of results, send page_no=2
page_size	The number of records to return per page. Minimum: 1 Maximum: 100 (or whatever your API limit is). Usage: A larger page_size reduces the number of API calls but increases payload size.
transaction_id	If you want to filter with a specific transaction id. Multiple ids are not supported. If a transaction id is passed, it has the highest priority. All the below mentioned filters are ommitted.
start_date	If you want to filter between 2 dates. Format: 2026-01-07 16:12:00 +05:30 Base timezone is in UTC.
end_date	If you want to filter between 2 dates Format: 2026-01-07 16:12:00 +05:30 Base timezone is in UTC.
last_updated_start	If you want to filter with the last updated date of a transaction. Format: 2026-01-07 16:12:00 +05:30 Base timezone is in UTC.
last_updated_end	If you want to filter with the last updated date of a transaction. Format: 2026-01-07 16:12:00 +05:30 Base timezone is in UTC.
customer_id	If you want to filter with a specific customer id. Multiple ids are not supported.
status	If you want to filter with the status.
currency	If you want to filter with the currency.

","urlObject":{"protocol":"https","path":["api","v1","external","transactions","list"],"host":["api","paybomb","net"],"query":[{"key":"page_no","value":"1"},{"key":"page_size","value":"10"},{"key":"transaction_id","value":"69d4ba22465443878a0045ba"},{"key":"start_date","value":"2025-10-29%2000%3A00%3A00%20+05%3A30"},{"key":"end_date","value":"2026-04-23%2000%3A00%3A00%20+05%3A30"},{"key":"last_updated_start","value":"2026-01-07%2016%3A12%3A00%20+05%3A30"},{"key":"last_updated_end","value":"2026-12-07%2016%3A12%3A00%20+05%3A30"},{"key":"customer_id","value":"NA"},{"key":"status","value":"paid"},{"key":"currency","value":"USD"},{"key":"is_sandbox","value":"true"}],"variable":[]}},"response":[{"id":"d52ce500-85e7-4973-ac86-1aa77f97447b","name":"Success","originalRequest":{"method":"GET","header":[{"key":"BrandId","value":"your-brand-id"},{"key":"Authorization","value":"Bearer Token"}],"url":{"raw":"https://api.paybomb.net/api/v1/external/transactions/list?page_no=1&page_size=10&start_date=2025-10-29%2000%3A00%3A00%20+05%3A30&end_date=2026-04-23%2000%3A00%3A00%20+05%3A30&last_updated_start=2026-01-07%2016%3A12%3A00%20+05%3A30&last_updated_end=2026-12-07%2016%3A12%3A00%20+05%3A30&customer_id=NA&status=paid¤cy=USD&is_sandbox=true","protocol":"https","host":["api","paybomb","net"],"path":["api","v1","external","transactions","list"],"query":[{"key":"page_no","value":"1"},{"key":"page_size","value":"10"},{"key":"transaction_id","value":"69d4ba22465443878a0045ba","disabled":true},{"key":"start_date","value":"2025-10-29%2000%3A00%3A00%20+05%3A30"},{"key":"end_date","value":"2026-04-23%2000%3A00%3A00%20+05%3A30"},{"key":"last_updated_start","value":"2026-01-07%2016%3A12%3A00%20+05%3A30"},{"key":"last_updated_end","value":"2026-12-07%2016%3A12%3A00%20+05%3A30"},{"key":"customer_id","value":"NA"},{"key":"status","value":"paid"},{"key":"currency","value":"USD"},{"key":"is_sandbox","value":"true"}]}},"status":"Bad Request","code":400,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Sun, 19 Apr 2026 14:11:10 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"X-Frame-Options","value":"ALLOW-FROM *"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"x-session-id","value":"c2111eb2-6314-4f0b-b546-4ae3ee123a44"},{"key":"Vary","value":"Origin"},{"key":"Vary","value":"Access-Control-Request-Method"},{"key":"Vary","value":"Access-Control-Request-Headers"},{"key":"Server","value":"cloudflare"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"0"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"Strict-Transport-Security","value":"max-age=31536000 ; includeSubDomains"},{"key":"X-Cache","value":"Error from cloudfront"},{"key":"Via","value":"1.1 6a91ddfdf36644f1344da228258d9082.cloudfront.net (CloudFront)"},{"key":"X-Amz-Cf-Pop","value":"IAD61-P10"},{"key":"X-Amz-Cf-Id","value":"lKDk7cJHKNy2cOdf_AWXk3GlUJdWC5slaGWaVfgUf1Fn0XXm7T7D7Q=="},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=YLhXcnCfKpMy2KQEcmek7bxnkI2lT3%2F5IQ8opo9ZpZ4E852qZoWIFsjJ%2BcmGZfTO7S1rWYnB3uzuGwMYwevQ%2F47w%2Bm6u51jrIfjuG3TDh08KGeWKRbR92ItXRYPoh1CgVmja\"}]}"},{"key":"CF-RAY","value":"9eec7f31f973c9b7-IAD"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"content\": [\n {\n \"transaction_id\": \"69e2146828bea6ca2e31bc85\",\n \"status\": \"paid\"\n },\n {\n \"transaction_id\": \"69e20fd928bea6ca2e31b17c\",\n \"status\": \"paid\"\n }\n ],\n \"currentPage\": 1,\n \"pageSize\": 2,\n \"totalElements\": 95,\n \"totalPages\": 48,\n \"first\": true,\n \"last\": false,\n \"hasNext\": true,\n \"hasPrevious\": false\n }\n}"}],"_postman_id":"9a97975d-1b2e-4755-8450-9fde938466b8"},{"name":"Get Detailed Transaction Details","id":"ddf12dd5-028a-445b-9faa-ebea11f5a7ac","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"BrandId","value":"your-brand-id"},{"key":"Authorization","value":"Bearer Token"}],"url":"https://api.paybomb.net/api/v1/external/transactions/data/69e20fd928bea6ca2e31b17c?page_no=1&page_size=10&include_subtransactions=true","description":"

Retrieves the complete details for a specific transaction. This includes customer info, payment method details, bank response codes, and hierarchy metadata (parent/child transactions).

Additional query parameters for this usecase:

\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Notes
include_subtransactions	Mandatory. Possible Values: true/false If true, includes child transactions (e.g., recurring payments).

","urlObject":{"protocol":"https","path":["api","v1","external","transactions","data","69e20fd928bea6ca2e31b17c"],"host":["api","paybomb","net"],"query":[{"key":"page_no","value":"1"},{"key":"page_size","value":"10"},{"key":"include_subtransactions","value":"true"}],"variable":[]}},"response":[{"id":"15e64e58-b6a5-4937-9300-d14ff6a6031c","name":"Success","originalRequest":{"method":"GET","header":[{"key":"BrandId","value":"your-brand-id"},{"key":"Authorization","value":"Bearer Token"}],"url":{"raw":"https://api.paybomb.net/api/v1/external/transactions/data/69e20fd928bea6ca2e31b17c?page_no=1&page_size=10&include_subtransactions=true","protocol":"https","host":["api","paybomb","net"],"path":["api","v1","external","transactions","data","69e20fd928bea6ca2e31b17c"],"query":[{"key":"page_no","value":"1"},{"key":"page_size","value":"10"},{"key":"include_subtransactions","value":"true"}]}},"status":"Bad Request","code":400,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Sun, 19 Apr 2026 14:13:09 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"X-Frame-Options","value":"ALLOW-FROM *"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"x-session-id","value":"3d9fb1d1-b30f-4c3e-a76f-6956e3731ad3"},{"key":"Vary","value":"Origin"},{"key":"Vary","value":"Access-Control-Request-Method"},{"key":"Vary","value":"Access-Control-Request-Headers"},{"key":"Server","value":"cloudflare"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"0"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"Strict-Transport-Security","value":"max-age=31536000 ; includeSubDomains"},{"key":"X-Cache","value":"Error from cloudfront"},{"key":"Via","value":"1.1 64d4305f6a0418824e90908ac490184e.cloudfront.net (CloudFront)"},{"key":"X-Amz-Cf-Pop","value":"IAD61-P10"},{"key":"X-Amz-Cf-Id","value":"COt7k0tEcVGSOSy8pTkHoOqGoG1lSgC9qz8baoKbgmPkAh5dq0GNjQ=="},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=hn0q1Q9Cqa9onXwzy%2F1Qeq8u4RTGt3q%2BZNFW29weO%2BOmtABh6y8XLnAH9%2FytCQEEOmNzdnvM0oPcQruiJvYqQQShCKOndiMKUnEksUPM9I9UMph4qP7s1ognTK%2BBhheXvIwO\"}]}"},{"key":"CF-RAY","value":"9eec821e0f4b172c-IAD"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"data\": {\n \"transaction_id\": \"69e20fd928bea6ca2e31b17c\",\n \"merchant_reference\": \"69e20fd928bea6ca2e31b17c\",\n \"customer_id\": \"NA\",\n \"amount\": 1.0,\n \"currency\": \"USD\",\n \"status\": \"paid\",\n \"session_id\": \"\",\n \"email\": \"aryangupta+3265@paybomb.tech\",\n \"merchant_name\": \"prithvimerch\",\n \"payment_method\": \"MASTER\",\n \"payment_flow\": \"payform\",\n \"issuing_bank\": \"PUBLIC BANK BERHAD\",\n \"created_at\": \"2026-04-17T10:47:53Z\",\n \"error_reason\": \"Transaction succeeded-APPROVED\",\n \"last_updated_at\": \"2026-04-17T10:49:14Z\",\n \"transaction_type\": \"parent\",\n \"fees\": [\n {\n \"type\": \"mdr\",\n \"amount\": 0.00,\n \"currency\": \"USD\"\n },\n {\n \"type\": \"decline_fee\",\n \"amount\": 0,\n \"currency\": \"USD\"\n },\n {\n \"type\": \"transaction_fee\",\n \"amount\": 0.1,\n \"currency\": \"USD\"\n },\n {\n \"type\": \"fraud_refund_fee\",\n \"amount\": 0,\n \"currency\": \"USD\"\n },\n {\n \"type\": \"refund_fee\",\n \"amount\": 0,\n \"currency\": \"USD\"\n },\n {\n \"type\": \"chargeback_fee\",\n \"amount\": 0,\n \"currency\": \"USD\"\n },\n {\n \"type\": \"extra_fee\",\n \"amount\": 0,\n \"currency\": \"USD\"\n }\n ],\n \"metadata\": {\n \"has_subtransactions\": false,\n \"total_subtransactions\": 0,\n \"transaction_hierarchy_level\": \"parent\"\n }\n }\n}"}],"_postman_id":"ddf12dd5-028a-445b-9faa-ebea11f5a7ac"}],"id":"ad99a973-2ffd-4196-b491-9ecc3a8c1eba","description":"

Overview

The Transaction Reporting APIs allow merchants to retrieve detailed logs of their payment activity programmatically. This is useful for:

Reconciliation: Matching Paybomb records with your internal order system.
\n
Audit Trails: Tracking the status history of specific transactions.
\n
Data Export: Pulling transaction data into your own analytics tools.
\n

There are two primary endpoints:

List Transactions: Retrieves a paginated list of all transactions for a specific Brand ID.
\n
Get Transaction Details: Retrieves the full data payload for a single transaction ID, including metadata and sub-transaction details.
\n

\n","_postman_id":"ad99a973-2ffd-4196-b491-9ecc3a8c1eba"},{"name":"Network Tokenisation","item":[{"name":"Merchant Configuration","item":[],"id":"47b5cfd8-5edb-4097-b047-3d4ad7a40421","description":"

Before you can use network tokenisation in your payment flow, the feature must be enabled and configured on your merchant account. This section walks through the setup steps in the Paybomb Dashboard.

Enabling Network Tokenisation

Network tokenisation requires activation at the merchant level. Follow these steps in the Paybomb Dashboard:

Log in to your Paybomb merchant account.
\n
Navigate to Merchant Details → Allowed Services.
\n
Enable “Allow Network Token” to activate tokenisation for your account.
\n

Admin Activation Required
Network tokenisation must first be enabled at the platform level by your Paybomb account administrator. If you do not see the “Allow Network Token” option in your dashboard, contact your Paybomb account manager to request activation.

\n\n

Paybomb Token Service Setup

After enabling network tokenisation, configure the Paybomb Token Service with your merchant details:

In the Paybomb Dashboard, navigate to Global Settings → Paybomb Token Service.
\n
Fill in all the required fields accurately.
\n
Enter your Category Code — this represents your merchant business type code (MCC).
\n
Click Save.
\n
After saving, verify that the status shows as Pending (visible in the top-right corner of the page).
\n
The status will automatically update to Active or Error once your token profile is created.
\n

\n\n

Status Update Timing: The status update from Pending to Active may take up to 1 hour. Do not attempt to use tokenisation APIs until the status shows Active. If the status changes to Error, contact your Paybomb account manager for resolution.

Status Values

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Meaning	Action Required
Pending	Your token service profile has been submitted and is being provisioned.	Wait for the status to update. This may take up to 1 hour.
Active	Token service is live and ready to use. You can now process tokenised transactions.	None — you are ready to integrate.
Error	There was a problem creating your token profile.	Contact your Paybomb account manager to resolve the issue.

List Saved Cards

Retrieve all saved card tokens for a given customer. Returns the last 4 digits of each card and its associated token_reference.

Use this API to display saved cards to the customer for selection before initiating a payment via the S2S API.

Query Parameters

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Type	Required	Description
`customerId`	string	Yes	Unique identifier for the customer. Must be URL-encoded if it contains special characters. Email addresses are case-sensitive.
`brandId`	string	Yes	Brand id of the merchant

Response Fields

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Type	Description
`card_last_four`	string	Last 4 digits of the stored card. Display to the customer for card selection.
`token_reference`	string	Unique reference for this saved card. Pass this in the S2S payment request or Delete Token request. Do not display to the customer.

Notes

The token_reference does not expire. It remains valid as long as the saved card has not been deleted.
\n
Show saved cards to the customer using card_last_four alongside a card brand icon (Visa / Mastercard).
\n
The token_reference should only be stored and used server-side.
\n

Display Tip

Show saved cards using cardlast4 alongside a card brand icon (Visa / Mastercard).
The token_reference should only be stored and used server-side.

\n","urlObject":{"path":["listSavedCards"],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"366a843a-b2a7-40a4-8926-987cc2aacf69","name":"Success","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{APIKey}}","type":"text"}],"url":{"raw":"https://app.paybomb.tech/api/v1/listSavedCards?customerId=test@paybomb.tech&brandId=fceb4dea-163c-492c-a9e6-beedd8539da8","host":["https://app.paybomb.tech/api/v1"],"path":["listSavedCards"],"query":[{"key":"customerId","value":"test@paybomb.tech"},{"key":"brandId","value":"fceb4dea-163c-492c-a9e6-beedd8539da8"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"[\n {\n \"card_last_four\": \"1003\",\n \"token_reference\": \"token_2bcf691f0f0347d6bcb38118d1bb31d5\"\n },\n {\n \"card_last_four\": \"6006\",\n \"token_reference\": \"token_e17dd98c66c14b37afaa62bd4770f915\"\n },\n {\n \"card_last_four\": \"6916\",\n \"token_reference\": \"token_7178bb7208614544a285656da38ae5ac\"\n }\n]"}],"_postman_id":"cb64a87c-3183-4c48-8a64-49651ddb0dc3"},{"name":"Purchase","id":"3400889e-fa47-4805-9100-f1a44e4e49a3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{APIKey}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"client\": {\n \"email\": \"customer@example.com\",\n \"country\": \"IN\",\n \"city\": \"Jaipur\",\n \"stateCode\": \"RJ\",\n \"street_address\": \"123 Main Street\",\n \"zip_code\": \"302001\",\n \"phone\": \"9999999999\"\n },\n \"purchase\": {\n \"currency\": \"USD\",\n \"products\": [\n {\n \"name\": \"Product Name\",\n \"price\": \"10.00\"\n }\n ]\n },\n \"brand_id\": \"{{BrandId}}\",\n \"success_redirect\": \"https://yoursite.com/success\",\n \"failure_redirect\": \"https://yoursite.com/failure\",\n \"pending_redirect\": \"https://yoursite.com/pending\",\n \"success_callback\": \"https://yoursite.com/webhook/success\",\n \"failure_callback\": \"https://yoursite.com/webhook/failure\"\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/api/v1/purchases","description":"

Purchase

Initiate a payment transaction. This is the standard Paybomb Purchase API.

When a customer completes the purchase on the Paybomb checkout page and opts to save their card, Paybomb provisions a network token in the background and generates a token_reference linked to the customer.

Mandatory Parameters

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Type	Description
`client.email`	string	Customer's email address. Please send it in smallcase
`client.city`	string	Customer's city.
`client.country`	string	ISO-3166 Alpha-2 country code, uppercase (e.g., IN, US, SG).
`client.stateCode`	string	State code, uppercase (e.g., RJ, CA, AL).
`client.street_address`	string	Customer's street address.
`client.zip_code`	string	Postal / ZIP code. US format: NNNNN or NNNNN-NNNN.
`purchase.currency`	string	ISO 4217 currency code (e.g., USD, EUR). Must be enabled on your account.
`purchase.products`	array	Array of product objects with `name` and `price`.
`brand_id`	string	Your Paybomb Brand ID from Dashboard.
`success_redirect`	string	URL to redirect customer after successful payment.
`failure_redirect`	string	URL to redirect customer after failed payment.

Optional Parameters

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Type	Description
`pending_redirect`	string	URL to redirect when payment is pending.
`success_callback`	string	Server-to-server webhook URL for success.
`failure_callback`	string	Server-to-server webhook URL for failure.
`merchantRef`	string	Your internal reference for this transaction.
`paymentMethod`	string	Pre-select payment method (e.g., VISA).
`client.phone`	string	Customer's phone number.

Key Response Fields

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Description
`id`	Unique purchase ID.
`checkout_url`	Redirect customer here to complete payment. Card saving happens during this step.
`direct_post_url`	URL for S2S payment submission.
`status`	Purchase status. Initially \"created\".

Network Tokenisation & Card Saving

When the customer completes payment via checkout_url and opts to save their card, Paybomb provisions a network token. The token_reference is then available via the List Saved Cards API.

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"53bb72ca-bd42-41cd-a2a7-d4a24841bd4e","id":"53bb72ca-bd42-41cd-a2a7-d4a24841bd4e","name":"APIs","type":"folder"}},"urlObject":{"path":["api","v1","purchases"],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"c26e38a4-a08d-4a50-9c33-e7e370a12e74","name":"Success","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{APIKey}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"client\": {\n \"email\": \"customer@example.com\",\n \"country\": \"IN\",\n \"city\": \"Jaipur\",\n \"stateCode\": \"RJ\",\n \"street_address\": \"123 Main Street\",\n \"zip_code\": \"302001\",\n \"phone\": \"9999999999\"\n },\n \"purchase\": {\n \"currency\": \"USD\",\n \"products\": [\n {\n \"name\": \"Product Name\",\n \"price\": \"10.00\"\n }\n ]\n },\n \"brand_id\": \"bd69e8a5-adcf-40de-9e43-2b87cb129a5e\",\n \"success_redirect\": \"https://yoursite.com/success\",\n \"failure_redirect\": \"https://yoursite.com/failure\",\n \"pending_redirect\": \"https://yoursite.com/pending\",\n \"success_callback\": \"https://yoursite.com/webhook/success\",\n \"failure_callback\": \"https://yoursite.com/webhook/failure\"\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/api/v1/purchases"},"status":"Accepted","code":202,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"purchaseId\": \"69b32e42250ac73495aefd50\",\n \"client\": {\n \"customerId\": \"NA\",\n \"email\": \"himanshu1@paybomb.tech\",\n \"full_name\": \"OpHM\",\n \"date_of_birth\": \"1800-01-01\",\n \"street_address\": \"SB-124\",\n \"country\": \"BR\",\n \"city\": \"DLJPR\",\n \"zip_code\": \"110001\",\n \"cc\": [],\n \"bcc\": [],\n \"stateCode\": \"DL\"\n },\n \"updated_on\": 1773350466,\n \"type\": \"purchase\",\n \"paymentMethod\": \"MASTER\",\n \"amountUnit\": \"MAJOR\",\n \"errorMsg\": \"\",\n \"errorCode\": \"NA\",\n \"force_recurring\": false,\n \"created_on\": 1773350466,\n \"merchantRef\": \"69b32e42250ac73495aefd50\",\n \"purchase\": {\n \"currency\": \"USD\",\n \"products\": [\n {\n \"name\": \"e-commerce\",\n \"quantity\": 1.0,\n \"price\": 10.0,\n \"discount\": 0,\n \"tax_percent\": \"0.00\"\n }\n ],\n \"total\": 10.0,\n \"requestAmount\": 10.0,\n \"language\": \"en\",\n \"notes\": \"\",\n \"debt\": 0,\n \"total_formatted\": 1.0,\n \"taxAmount\": 0.0,\n \"taxPercent\": 0.0,\n \"request_client_details\": [],\n \"email_message\": \"\"\n },\n \"issuer_details\": {\n \"website\": \"\",\n \"legal_street_address\": \"\",\n \"legal_country\": \"\",\n \"legal_city\": \"\",\n \"legal_zip_code\": \"\",\n \"bank_accounts\": [\n {}\n ],\n \"legal_name\": \"brand\",\n \"brand_name\": \"brand\",\n \"registration_number\": \"\",\n \"tax_number\": \"\"\n },\n \"transaction_data\": {\n \"payment_method\": \"\",\n \"flow\": \"payform\",\n \"extra\": {},\n \"country\": \"\",\n \"attempts\": []\n },\n \"status\": \"CREATED\",\n \"status_history\": [\n {\n \"status\": \"created\",\n \"timestamp\": 1773350466\n }\n ],\n \"is_test\": false,\n \"brand_id\": \"5949f2ac-b5a3-4ee4-b585-ad4cf9a6db18\",\n \"send_receipt\": false,\n \"is_recurring_token\": false,\n \"skip_capture\": false,\n \"reference_generated\": \"PS1060\",\n \"issued\": \"2026-03-12\",\n \"due\": 1773350466,\n \"refund_upto\": 0,\n \"cc_descriptor\": \"\",\n \"fraudScore\": \"NA\",\n \"trustScore\": \"NA\",\n \"extraFee\": \"0\",\n \"paidOn\": 0,\n \"receivedAmt\": 0.0,\n \"taxAmount\": 0.0,\n \"surcharge\": 0.0,\n \"surchargeType\": \"\",\n \"sessionId\": \"\",\n \"refund_availability\": \"NONE\",\n \"refundable_amount\": 0.0,\n \"success_redirect\": \"https://google.com/\",\n \"failure_redirect\": \"https://facebook.com/\",\n \"pending_redirect\": \"https://app.paybomb.tech\",\n \"cancel_redirect\": \"\",\n \"success_callback\": \"https://your.success.callback.com\",\n \"failure_callback\": \"https://your.failure.callback.com\",\n \"platform\": \"API\",\n \"created_from_ip\": \"110.235.229.171\",\n \"checkout_url\": \"https://api.choicepay.ca/payments/1b73d31d178113798afa0157c8805ef0/\",\n \"direct_post_url\": \"https://api.choicepay.ca/api/v1/p/69b32e42250ac73495aefd50/\",\n \"payoutProcess\": false\n}"}],"_postman_id":"3400889e-fa47-4805-9100-f1a44e4e49a3"},{"name":"S2S Payment","id":"ffaf923d-e245-44ba-a0df-f67dd78b9ff4","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{APIKey}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"Token_reference\": \"token_7178aa7208614544a285656da38ae5ac\",\n \"cvc\": \"791\",\n \"remember_card\": \"off\",\n \"remote_ip\": \"157.38.242.7\",\n \"user_agent\": \"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36\",\n \"accept_header\": \"text/html\",\n \"language\": \"en-US\",\n \"java_enabled\": false,\n \"javascript_enabled\": true,\n \"color_depth\": 24,\n \"utc_offset\": 0,\n \"screen_width\": 1920,\n \"screen_height\": 1080\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/api/v1/p/{{brandId}}/?s2s=true","description":"

S2S Payment

Process a payment using a saved card's token_reference. Paybomb resolves the token reference to the underlying network token and processes the payment securely. If the selected MID does not accept tokens, Paybomb automatically falls back to the card number.

S2S Input Scenarios

The S2S API accepts different input types depending on the scenario:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Scenario	What to Send	What Paybomb Does
New card (first-time customer)	Full card details	Paybomb tokenises the card. If the MID supports tokens, the transaction uses the token; otherwise, the card number is used.
Returning customer (tokenised with Paybomb)	`token_reference` from List Saved Cards	Paybomb uses the stored token and generates a new cryptogram. Falls back to card number if MID doesn't accept tokens.

Request Body

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Type	Required	Description
`token_reference`	string	Conditional	Token reference from List Saved Cards. Required when paying with a Paybomb-tokenised card.
`cvc`	string	Yes	Card CVC/CVV. Required even when `token_reference` is provided, for 3DS authentication.
`remember_card`	string	No	`\"on\"` to save card, `\"off\"` to skip. Use `\"off\"` with saved tokens.
`remote_ip`	string	Yes	Cardholder's IP address.
`user_agent`	string	Yes	Browser User-Agent string.
`accept_header`	string	Yes	Browser Accept header.
`language`	string	Yes	Browser language (e.g., `\"en-US\"`).
`java_enabled`	boolean	Yes	Java enabled in browser.
`javascript_enabled`	boolean	Yes	JavaScript enabled in browser.
`color_depth`	integer	Yes	Screen colour depth.
`utc_offset`	integer	Yes	UTC timezone offset (minutes).
`screen_width`	integer	Yes	Screen width (px).
`screen_height`	integer	Yes	Screen height (px).

Token Reference in Response

Scenario 1 (New card via S2S): token_reference returned in Check Status and Webhook.
\n
Scenario 2 (Existing token_reference): token_reference returned in response and Webhook.
\n

Important Notes

CVC is required even when using a token_reference.
\n
All browser fields are required for 3D Secure authentication.
\n
Response follows the standard Paybomb payment response format.
\n

Must be \"true\" for server-to-server requests.

\n","type":"text/plain"},"key":"s2s","value":"true"}],"variable":[]}},"response":[{"id":"d2b2251f-055c-4475-a13f-273a3d61a978","name":"Success","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{APIKey}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"Token_reference\": \"token_7178aa7208614544a285656da38ae5ac\",\n \"cvc\": \"791\",\n \"remember_card\": \"off\",\n \"remote_ip\": \"157.38.242.7\",\n \"user_agent\": \"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36\",\n \"accept_header\": \"text/html\",\n \"language\": \"en-US\",\n \"java_enabled\": false,\n \"javascript_enabled\": true,\n \"color_depth\": 24,\n \"utc_offset\": 0,\n \"screen_width\": 1920,\n \"screen_height\": 1080\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://app.paybomb.tech/api/v1/api/v1/p/6980e509b5e99e61f3bd4ccf/?s2s=true","host":["https://app.paybomb.tech/api/v1"],"path":["api","v1","p","6980e509b5e99e61f3bd4ccf",""],"query":[{"key":"s2s","value":"true"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": \"pending\",\n \"callback_url\": \"http://18.214.100.20/api/v1/payment/64b034ecc6dccf7d329d9eb3/\",\n \"method\": \"GET\"\n}"}],"_postman_id":"ffaf923d-e245-44ba-a0df-f67dd78b9ff4"},{"name":"Delete Token","id":"1ab28816-58a5-44ba-9651-eb4064848efe","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[{"key":"Authorization","value":"Bearer {{APIKey}}","type":"text"}],"url":"https://app.paybomb.tech/api/v1/tokens/v1/deleteToken/{{token_reference}}","description":"

Delete Token

Permanently delete a saved card and deactivate the associated network token. This action is irreversible.

Path Parameters

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Type	Required	Description
`token_reference`	string	Yes	The `token_reference` of the saved card to delete. Obtained from the List Saved Cards API.

Important Notes

Deleting a token is permanent. The token_reference can no longer be used for payments.
\n
The associated network token is deactivated with the card network.
\n
If the customer wants to pay with this card again, they will need to re-enter their card details.
\n

When to Delete

Customer explicitly requests removal of their saved card.
\n
GDPR or data retention compliance when a customer closes their account.
\n
Consider implementing a \"Remove Card\" option in your account management UI.
\n

Overview

This feature is designed for high-velocity industries that require frictionless, real-time payouts, such as:

Gaming & Betting: Real-time withdrawal of player winnings.
\n
Marketplaces: Payouts to sellers or service providers.
\n
Corporate Disbursements: Instant insurance claims, rebates, or compensation payments.
\n
Merchant Settlements: Faster access to processed funds for sub-merchants.
\n

Integration Steps

Enable OCT: Ensure \"Push to Card\" permissions are enabled for your merchant account in the Paybomb Merchant Portal.
\n
Collect Card Details: Use a secure method to collect the recipient's card number and expiry date or can you Paybomb's cashier to do that.
\n
Execute Payout: Call the /payout endpoint with the OCT-specific payout method.
\n
Handle Webhooks: Listen for the paid or failure events to update your internal records.
\n

Mandatory parameters in the request body:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Required	Notes
client.email	Yes	The customer's email. Please send it in small case.
client.phone	Yes	The customer's phone number along with the country code. Example: +91 9634088651
client.city	Yes	The customer's city.
client.country	Yes	ISO-3166 Country Code. Must be upper case. Example “SG” (Alpha2)
client.stateCode	Optional	Example “AL”, “XZ”. Must be in upper case.
Client.street_address	Optional	The customer's address.
client.zip_code	Optional	The customer's ZIP or postal code. If country=US, zip format must be NNNNN or NNNNN-NNNN.
currency	Yes	ISO 4217 code for currency you want to send the transaction in. Please note, the currency has to be enabled by the account manager for your account.
amount	Yes	amount in decimal format. example 1: EUR 5 , should be sent as 5.00 example 2: USD 10 and 37 cents , should be sent as 10.37
payoutMethod	Optional	example: PAYOUT-CARDS
success_redirect	Yes	URL to send the user if the transactions is successful.
pending_redirect	Yes	URL to send the user if the transactions is in pending.
failure_redirect	Yes	URL to send the user if the transactions is unsuccessful.
Purpose	Optional	The purpose of doing a payout.
extraParam.token_reference	Yes	Paybomb Token

Note:

If the merchant is not PCI DSS compliant then they will need to use our cashier and we will show the user all the saved cards for him/her. Based on the card chosen, Paybomb will pick up the token_reference from our Back end.

If the merchant is PCI DSS compliant then they can use the payout API and send the token reference as shown above.

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"53bb72ca-bd42-41cd-a2a7-d4a24841bd4e","id":"53bb72ca-bd42-41cd-a2a7-d4a24841bd4e","name":"APIs","type":"folder"}},"urlObject":{"path":["payout",""],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"17249c81-3911-4914-b294-09817233a990","name":"Success","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"body":{"mode":"raw","raw":"{\n \"client\": {\n \"email\": \"rahul@gmail.com\",\n \"country\": \"GB\",\n \"city\": \"London\",\n \"stateCode\": \"QLD\",\n \"full_name\": \"Rahul Jain\",\n \"street_address\": \"10 New Burlington Street Apt. 214\",\n \"zip_code\": \"W1S 3BE\",\n \"phone\": \"+44 9876543210\",\n \"gender\": \"M\",\n \"date_of_birth\": \"1970-07-10\"\n },\n \"purpose\": \"Testing cards payout\",\n \"currency\": \"GBP\",\n \"merchantRef\": \"YOUR ORDER ID\", // optional\n \"payoutMethod\": \"PAYOUT-CARDS\",\n \"amount\": 100.0,\n \"success_redirect\": \"https://your.success.redirect.com\",\n \"pending_redirect\": \"https://your.pending.redirect.com\",\n \"failure_redirect\": \"https://your.failure.redirect.com\",\n \"success_callback\": \"https://your.success.callback.com\",\n \"failure_callback\": \"https://your.failure.callback.com\",\n \"extraParam\": {\n \"token_reference\": \"token_ref\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/payout/"},"status":"Unauthorized","code":401,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Fri, 13 Mar 2026 00:01:17 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"X-Frame-Options","value":"ALLOW-FROM *"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"x-session-id","value":"3ef27476-f274-4f6a-bb18-4c37e01d6dc2"},{"key":"Vary","value":"Origin"},{"key":"Vary","value":"Access-Control-Request-Method"},{"key":"Vary","value":"Access-Control-Request-Headers"},{"key":"Server","value":"cloudflare"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"0"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"Strict-Transport-Security","value":"max-age=31536000 ; includeSubDomains"},{"key":"X-Cache","value":"Error from cloudfront"},{"key":"Via","value":"1.1 05a63efd5ebb043211ccf075f3a8aa68.cloudfront.net (CloudFront)"},{"key":"X-Amz-Cf-Pop","value":"IAD61-P10"},{"key":"X-Amz-Cf-Id","value":"Iw6KuTkxZqm0RH8GJOXAh7uLEPJ6wj8OJbaFWdN_qDx31b5TSinnIA=="},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=g%2FW8jRMDFXKvTeXNugr1sgR4%2FoTXfyEHsscr3hqeIr2aPhFEVlSs%2FGiTjFw09%2BReVDjxT2esg2Wg0fdBf4oD3snlEv4p1JkITe2l7oLC%2Bkg%3D\"}]}"},{"key":"CF-RAY","value":"9db6c366997196a2-IAD"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"payoutId\": \"6977137755e0628e3600c562\",\n \"client\": {\n \"email\": \"rahul@gmail.com\",\n \"country\": \"GB\",\n \"city\": \"London\",\n \"stateCode\": \"QLD\",\n \"full_name\": \"Rahul Jain\",\n \"street_address\": \"10 New Burlington Street Apt. 214\",\n \"zip_code\": \"W1S 3BE\",\n \"phone\": \"+44 9876543210\",\n \"gender\": \"M\",\n \"date_of_birth\": \"1970-07-10\"\n },\n \"updated_on\": 1769411447,\n \"extraParam\": {\n \"token_reference\": \"token_ref\"\n },\n \"payoutMethod\": \"PAYOUT-CARDS\",\n \"amountUnit\": \"MAJOR\",\n \"amount\": 100.0,\n \"errorMsg\": \"\",\n \"purpose\": \"Testing cards payout\",\n \"created_on\": 1769411447,\n \"merchantRef\": \"YOUR ORDER ID\",\n \"status\": \"PAID\",\n \"status_history\": [\n {\n \"status\": \"created\",\n \"timestamp\": 1769411447\n },\n {\n \"status\": \"payout_in_process\",\n \"timestamp\": 1769411447\n },\n {\n \"status\": \"paid\",\n \"timestamp\": 1769411447\n },\n\n ],\n \"currency\": \"GBP\",\n \"extraFee\": \"0\",\n \"paymentOn\": 0,\n \"checkout_url\": \"https://test4.paymentsclub.net/payout/092e59f94279a3742fa3715fe9a2112a/\",\n \"taxAmount\": 0.0,\n \"taxPercent\": 0.0,\n \"success_redirect\": \"https://your.success.redirect.com\",\n \"pending_redirect\": \"https://your.pending.redirect.com\",\n \"failure_redirect\": \"https://your.failure.redirect.com\",\n \"success_callback\": \"https://your.success.callback.com\",\n \"failure_callback\": \"https://your.failure.callback.com\"\n \"redirectType\": \"POST\",\n \"sessionId\": \"\",\n \"surcharge\": 0.0,\n \"surchargeType\": \"\",\n \"trxMethod\": \"CARDS\",\n \"success_callback\": \"\",\n \"failure_callback\": \"\"\n}"}],"_postman_id":"d085eb3f-9e33-47d7-9597-7c599fc1429a"}],"id":"53bb72ca-bd42-41cd-a2a7-d4a24841bd4e","description":"

Network tokenisation in Paybomb uses four APIs. Together they cover the complete flow: retrieving saved cards, initiating a purchase (with card saving), processing payments with saved tokens, and deleting tokens.

Q1: Do I need to change my existing integration to use network tokenisation?
No. If you already use the Paybomb Purchase API and the S2S API with token_reference, your integration is already compatible. You just need to enable and configure network tokenisation in your Dashboard (see Section 3).

Q2: What is a token_reference?
A token_reference (e.g., token_7178aa7208614544a285656da38aefac) is Paybomb’s internal identifier for a saved card. You use it to charge the saved card or delete it. It is not the card number or the network token — Paybomb manages those internally.

Q3: Does the token_reference expire?
No. The token_reference does not expire. It remains valid as long as the saved card has not been deleted.

Q4: What happens when a customer’s card expires or is replaced?

The card network automatically updates the data linked to the token. Your token_reference stays the same, and payments continue to work without action from you or the customer.

Q5: Is CVC required even when using a token_reference?
Yes. CVC is required even when a token_reference is provided. This is needed for 3D Secure authentication on customer-initiated transactions.

Q6: What if a card doesn’t support network tokenisation?
Paybomb handles this automatically. If a card is not eligible, or if the selected MID does not accept tokens, Paybomb falls back to the card number. The API response and flow remain the same.

Q7: How long does the token service setup take?
After saving your configuration in Dashboard → Global Settings → Paybomb Token Service, the status changes to Pending. It may take up to 1 hour to update to Active. Do not use tokenisation APIs until the status is Active.

Q8: Are email addresses case-sensitive for token lookup?
Yes. Email addresses are case-sensitive. Ensure consistent formatting (always lowercase) when creating and retrieving tokens to avoid duplicate or missing entries.

Q9: How do I delete a saved card?
Use the Delete Token API (DELETE /tokens/v1/deleteToken/{token_reference}). This permanently removes the card and deactivates the network token.

Q10: Is there an additional cost?
Pricing details are communicated by your Paybomb account manager. Some card networks offer reduced interchange fees for tokenised transactions, which may offset service costs.

Overview

Paybomb supports Network Tokenisation to help merchants process card payments with improved security, higher authorisation rates, and seamless card lifecycle management.

Network tokenisation works entirely behind the scenes. When a cardholder saves their card during a purchase, Paybomb securely provisions a network token and returns a token_reference. You use this reference for all future payments — you never handle actual card numbers or network tokens directly.

Benefits

Higher Approval Rates — Payments made with network tokens are recognised as more secure by issuers.
\n
Automatic Card Updates — Card replacements are handled silently by the card network.
\n
Stronger Security — Each token is merchant-specific and protected by a per-transaction cryptogram.
\n
Reduced PCI Burden — Store token_reference instead of card numbers.
\n
Zero Integration Overhead — Your existing API integration works as-is.
\n

API Flow

Network tokenisation is fully managed by Paybomb. The integration follows the standard Paybomb payment APIs:

The Merchant Flow

Call the List Saved Cards API to check if the customer has saved cards
\n
If no saved cards exist, initiate a new payment via the Purchase + S2S API
→ If the merchant opts to save the customer card, Paybomb provisions a network token
→ Customer completes payment
→ A token_reference is generated and linked to the customer and card
\n
For returning customers with saved cards:
→ Display saved cards using cardlast4 from List Saved Cards
→ Customer selects a card and provides CVC
→ Submit token_reference + CVC via the purchase + S2S API
\n
To remove a saved card, call the Delete Token API.
\n

Network tokenisation happens behind the scenes with no additional API calls and no changes to your existing flow.

List Saved Cards — Check if the customer has saved cards
\n
Purchase — Initiate a new payment (customer can save card during checkout)
\n
S2S Payment — Charge a saved card using token_reference
\n
Delete Token — Remove a saved card permanently
\n

Key Takeaway

You never see or handle the actual network token. Paybomb abstracts it entirely behind the token_reference. Your integration stays simple while your customers get the security and reliability benefits of network tokenisation.

Environments

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Environment	Base URL
Sandbox	`https://app.paybomb.tech/api/v1` Note: set the Sandbox flag true (checked) in your merchant account. As shown in the image below
Production	`https://app.paybomb.tech/api/v1`

Before integrating the pre-authorisation flow, ensure you have the following:

2.1 Account Setup

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Requirement	Details
Paybomb Merchant Account	An active merchant account with API access enabled.
API Key	Your unique API key, available from Dashboard → API Keys.
Brand ID	Your brand identifier, found in Dashboard → Account Settings.
Webhook URL (Recommended)	A publicly accessible HTTPS endpoint to receive transaction status updates.

2.2 Environments

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Environment	Base URL	Notes
Sandbox	https://app.paybomb.tech/api/v1	Set the Sandbox flag to true in your merchant account.
Production	https://app.paybomb.tech/api/v1	Live transactions. Ensure KYB verification is complete.

2.3 Authentication

All API requests must include your API key in the request header.
Paybomb uses bearer token authentication.

Authorization: Bearer {your_api_key}

Content-Type: application/json

Important: Never expose your API key in client-side code or public repositories. All API calls must be made server-to-server.

The pre-authorisation and capture flow involves three distinct stages. Below is a high-level summary of each path the transaction can follow after authorisation.

3.1 Flow Summary

Step 1 - The merchant sends a pre-authorisation request to reserve funds on the customer’s card. If successful, the transaction enters an AUTHORISED state.

Step 2a (Capture Path) - The merchant sends a capture request for the full or partial authorised amount. On success, the transaction moves to CAPTURED and funds are settled.

Step 2b (Void Path) - If the merchant no longer needs to collect the payment, they send a void request. The hold is released and the transaction moves to VOIDED.

3.2 State Transition Diagram

The following diagram describes all possible states:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

From State	Action	To State (Terminal)	Description
CREATED	Pre-Authorise	PREAUTHORIZED	Funds are held on the customer’s card.
PREAUTHORIZED	Capture (Full)	PAID	Full authorised amount is settled.
PREAUTHORIZED	Capture (Partial)	PARTIALLY_CAPTURED	Part of the authorised amount is settled; remainder released.
PREAUTHORIZED	Void	CANCELLED	Hold is released. No funds are collected.
PREAUTHORIZED	(Expiry)	EXPIRED	Authorisation window elapsed without capture. Funds auto-released. 30 days default.
PAID	Refund	REFUNDED	Post-capture return of funds (separate API).
PARTIALLY_CAPTURED	Refund	PARTIALLY_REFUNDED	Post partial capture return of funds (separate API).

ℹ️ Note

Once a transaction is PAID or VOIDED, it cannot be reversed through this flow. Use the Refund API for post-capture reversals.

3.3 Authorisation Validity Periods

Card networks enforce maximum hold periods. If you do not capture within the validity window, the authorisation expires automatically and funds are released.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Card Scheme	Standard Hold Period	Extended Hold (if available)
Visa	7 days	Up to 30 days (select MCCs)
Mastercard	7 days	Up to 30 days (select MCCs)
American Express	7 days	Up to 30 days
Discover	10 days	N/A

⚠️ Best Practice

Capture as soon as the order is ready to ship or the service is delivered. Delaying capture increases the risk of authorisation expiry and declines.

\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"659d03d3-e86c-4de8-8734-298d55406625"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"24a293f0-465e-4f80-8a65-81be66fca998"}}],"_postman_id":"d857cd6c-5a92-4966-bbda-cab07788ec76"},{"name":"APIs","item":[{"name":"Purchase","id":"83eeaa20-73b3-4e74-ad3b-9c5bb88bb855","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"email\": \"example@paybomb.tech\",\r\n \"country\": \"IN\",\r\n \"city\": \"123\",\r\n \"stateCode\": \"ca\",\r\n \"street_address\": \"test test\",\r\n \"zip_code\": \"234567\",\r\n \"phone\": \"+91 9999999999\"\r\n },\r\n \"purchase\": {\r\n \"products\": [\r\n {\r\n \"name\": \"dk\",\r\n \"price\": \"10\"\r\n }\r\n ]\r\n },\r\n \"status\": \"created\",\r\n \"brand_id\": \"bd69e8a5-adcf-40de-9e43-2b87cb129a5e\",\r\n \"skip_capture\": true,\r\n \"merchantRef\": \"d9db7ec0-f94c-4a9d-8883-54c19c222d81\",\r\n \"success_redirect\": \"https://your.success.redirect.com\",\r\n \"pending_redirect\": \"https://your.pending.redirect.com\",\r\n \"failure_redirect\": \"https://your.failure.redirect.com\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/purchases","description":"

Use this endpoint to authorise a payment without capturing it. This places a temporary hold on the customer’s funds for the specified amount.

To Initiate a payment, the very first call to make is /purchases with the required data in the request body.

To generate a Purchase, you are required to provide the Brand ID (in the request body) and API key (in the header) Both can be located in the Dashboard section of your merchant account login.

The request body structure is shown on the request body of the example request shown here.

The following (see table below) are the mandatory parameters that are required to create a purchase request.

Mandatory parameters in the request body:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Notes
client.email	The customer's email.
client.city	The customer's city.
client.country	ISO-3166 Country Code. Must be upper case. Example “SG” (Alpha2)
client.stateCode	Example “AL”, “XZ”. Must be in upper case.
Client.street_address	The customer's address.
client.zip_code	The customer's ZIP or postal code. If country=US, zip format must be NNNNN or NNNNN-NNNN.
purchase.currency	ISO 4217 code for currency you want to send the transaction in. Please note, the currency has to be enabled by the account manager for your account.
purchase.products	An object which contains the list of products which the customer is buying.
purchase.products.name	The name of the product.
purchase.products.price	Price in decimal format. example 1: EUR 5 , should be sent as 5.00 example 2: USD 10 and 37 cents , should be sent as 10.37
brand_id	Obtain from Dashboard section of your merchant account login.
success_redirect	URL to send the user if the transactions is successful.
pending_redirect	URL to send the user if the transactions is in pending.
failure_redirect	URL to send the user if the transactions is unsuccessful.

Additional parameters for this usecase:

\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Notes
skip_capture	true

Essential Optional Parameters

merchantRef

The merchantRef parameter, although not mandatory, is strongly advised for merchants to specify. Its inclusion offers two significant advantages for the merchant:

Prevention of Duplicate Requests: When a merchantRef is utilized, it acts as a unique identifier. This means that if a second purchase request is made using the same merchantRef (reference number), the system will recognize it and prevent duplicate transactions from occurring. This prevents unintended or duplicate purchases.
\n
Facilitation of Transaction Retrieval: In situations where the response from the initial purchase request times out or the 'purchaseId' isn't received, having the merchantRef allows the merchant to retrieve detailed transaction information. This ensures they can track and access the specific purchase details related to that reference, even if the immediate response was not received.
\n

However, if the merchant does not specify the 'merchantRef' parameter, the platform will automatically assign and use an internal 'purchaseId' as a reference for that transaction.

Upon successul create on a Purchase you'd get a \"purchaseId\" . Use this ID for the next step in Server to server call by calling p/{purchaseId}/?s2s=true .

paymentMethod

Errors

If there are any errors then it'll be in the format of :

{\n    \"message\": \"descriptive error message\",\n    \"code\": \"error_code\"\n}\n\n

Possible Error Messages

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Error Messages
Allowed Limit for this card for particular time period has been consumed
some Mandatory Parameter are missing
Invalid format of Date_of_Birth [allowed format: yyyy-mm-dd]
Invalid Email Format
Please submit Valid Alpha2 Country Code Ex:(AF,IN) in \\\"country\\\" parameter
Please pass Valid State Code
Please pass valid street address in \\\"street_address\\\" parameter
Please pass valid city name in \\\"city\\\" parameter
Please pass valid postal Code name in \\\"zip_code\\\" parameter
You are not Allowed for Live Transaction
Merchant Limit is not set
Minimum amount is not set for this merchant
Brand not found !
Your charges setting is incomplete .Plese Contact to Administrator.
Only {{currencyCode}} currency is allowed.
Transaction amount must be equal or greater to minimum trans amount
Invalid_Parameter You'd usually get it when one or more mandatory parameters are not present in the request.

","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"55300479-5b71-4b30-84e2-5ba8021bff9c","id":"55300479-5b71-4b30-84e2-5ba8021bff9c","name":"APIs","type":"folder"}},"urlObject":{"path":["purchases"],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"52a7f833-b6db-44d9-9910-77abc5e302aa","name":"Purchase","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"client\": {\r\n \"email\": \"example@paybomb.tech\",\r\n \"country\": \"IN\",\r\n \"city\": \"123\",\r\n \"stateCode\": \"ca\",\r\n \"street_address\": \"test test\",\r\n \"zip_code\": \"234567\",\r\n \"phone\": \"+91 9999999999\"\r\n },\r\n \"purchase\": {\r\n \"products\": [\r\n {\r\n \"name\": \"dk\",\r\n \"price\": \"10\"\r\n }\r\n ]\r\n },\r\n \"status\": \"created\",\r\n \"brand_id\": \"bd69e8a5-adcf-40de-9e43-2b87cb129a5e\",\r\n \"skip_capture\": true,\r\n \"merchantRef\": \"d9db7ec0-f94c-4a9d-8883-54c19c222d81\",\r\n \"success_redirect\": \"https://your.success.redirect.com\",\r\n \"pending_redirect\": \"https://your.pending.redirect.com\",\r\n \"failure_redirect\": \"https://your.failure.redirect.com\",\r\n \"success_callback\": \"https://your.success.callback.com\",\r\n \"failure_callback\": \"https://your.failure.callback.com\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/purchases"},"status":"Accepted","code":202,"_postman_previewlanguage":"json","header":[{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"1; mode=block"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"X-Frame-Options","value":"DENY"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Date","value":"Thu, 13 Jul 2023 17:22:14 GMT"},{"key":"Keep-Alive","value":"timeout=60"},{"key":"Connection","value":"keep-alive"}],"cookie":[],"responseTime":null,"body":"{\n \"purchaseId\": \"64b032c3c6dccf7d329d9e7e\",\n \"client\": {\n \"bank_account\": \"\",\n \"bank_code\": \"\",\n \"email\": \"dev@paybomb.tech\",\n \"phone\": \"\",\n \"full_name\": \"\",\n \"date_of_birth\": \"\",\n \"personal_code\": \"\",\n \"street_address\": \"test test\",\n \"country\": \"IN\",\n \"city\": \"123\",\n \"zip_code\": \"234567\",\n \"shipping_street_address\": \"\",\n \"shipping_country\": \"\",\n \"shipping_city\": \"\",\n \"shipping_zip_code\": \"\",\n \"cc\": [],\n \"bcc\": [],\n \"legal_name\": \"\",\n \"brand_name\": \"\",\n \"registration_number\": \"\",\n \"tax_number\": \"\",\n \"stateCode\": \"ca\"\n },\n \"updated_on\": 1689268934,\n \"type\": \"purchase\",\n \"force_recurring\": false,\n \"created_on\": 1689268934,\n \"purchase\": {\n \"currency\": \"USD\",\n \"products\": [\n {\n \"name\": \"dk\",\n \"quantity\": 1,\n \"price\": 10,\n \"discount\": 0,\n \"tax_percent\": \"0.00\"\n }\n ],\n \"total\": 10,\n \"language\": \"en\",\n \"notes\": \"\",\n \"debt\": 0,\n \"total_formatted\": 1,\n \"request_client_details\": [],\n \"timezone\": \"America/Edmonton\",\n \"email_message\": \"\"\n },\n \"issuer_details\": {\n \"website\": \"\",\n \"legal_street_address\": \"\",\n \"legal_country\": \"\",\n \"legal_city\": \"\",\n \"legal_zip_code\": \"\",\n \"bank_accounts\": [\n {\n \"bank_account\": \"\",\n \"bank_code\": \"\"\n }\n ],\n \"legal_name\": \"shoes\",\n \"brand_name\": \"shoes\",\n \"registration_number\": \"\",\n \"tax_number\": \"\"\n },\n \"transaction_data\": {\n \"payment_method\": \"\",\n \"flow\": \"payform\",\n \"extra\": {},\n \"country\": \"\",\n \"attempts\": []\n },\n \"status\": \"CREATED\",\n \"status_history\": [\n {\n \"status\": \"created\",\n \"timestamp\": 1689268934\n }\n ],\n \"is_test\": false,\n \"brand_id\": \"bd69e8a5-adcf-40de-9e43-2b87cb129a5e\",\n \"is_recurring_token\": false,\n \"reference_generated\": \"PS161\",\n \"merchantRef\":\"d9db7ec0-f94c-4a9d-8883-54c19c222d81\",\n \"issued\": \"2023-07-13\",\n \"due\": 1689268934,\n \"refund_upto\": 0,\n \"cc_descriptor\": \"\",\n \"refund_availability\": \"NONE\",\n \"refundable_amount\": 0,\n \"success_redirect\": \"https://your.success.redirect.com\",\n \"failure_redirect\": \"https://your.failure.redirect.com\",\n \"cancel_redirect\": \"\",\n \"success_callback\": \"\",\n \"platform\": \"API\",\n \"created_from_ip\": \"149.86.53.48\",\n \"checkout_url\": \"http://18.214.100.20/payments/64b032c3c6dccf7d329d9e7e/\",\n \"direct_post_url\": \"http://18.214.100.20/api/v1/p/64b032c3c6dccf7d329d9e7e/\"\n}"}],"_postman_id":"83eeaa20-73b3-4e74-ad3b-9c5bb88bb855"},{"name":"S2S","id":"38a27849-024f-4407-83e2-744ba0d22dce","protocolProfileBehavior":{"disableUrlEncoding":false,"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"cardholder_name\": \"dk\",\r\n \"card_number\": \"4111111111111111\",\r\n \"expires\": \"10/23\",\r\n \"cvc\": \"345\",\r\n \"remember_card\": \"on\",\r\n \"remote_ip\": \"157.38.242.7\",\r\n \"user_agent\": \"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36\",\r\n \"accept_header\": \"text/html\",\r\n \"language\": \"en-US\",\r\n \"java_enabled\": false,\r\n \"javascript_enabled\": true,\r\n \"color_depth\": 24,\r\n \"utc_offset\": 0,\r\n \"screen_width\": 1920,\r\n \"screen_height\": 1080\r\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/p/64bff4fff63e36669499e9c8/?s2s=true","description":"

This API would be the 2nd in sequence to call if the call to /purchases/ was successful in step 1. and you want to do the transaction via Server-to-Server mode.

The request body would contain the details of the card that's to be transacted upon.

Mandatory parameters in request body:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Notes
remote_ip	IP address of the customer’s device used for transaction. Helps in fraud checks and risk scoring. Ex- 157.38.242.7
user_agent	Full browser and operating system details captured from HTTP header. EX- Chrome/5.0 (X11; Linux x86_64)
accept_header	Browser’s accepted content types (from HTTP header). Used for validating request origin and device info. EX- text/html

Note:
If you want to use token_reference for doing a card transaction, please have a look at Network Tokenisation Section.

Essential parameters in request body:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Notes
cardholder_name	Name of the cardholder
card_number	The card numbers Must be 10-20 characters.
expires	must be greater than the current month/year.
cvc	3 or 4 digit

**
Other optional parameters in request body:**

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Notes
language	Preferred language of the user’s browser . EX - en-US
java_enabled	Indicates if Java is enabled in the browser. Helps PSPs in device profiling. Ex- true/false
javascript_enabled	Indicates if JavaScript is enabled in the client browser. Used for 3DS or risk-based checks. Ex- true
color_depth	Bit depth of the display screen. Ex- 24
utc_offset	Difference in minutes between local time and UTC. Used for location and timezone checks. Ex- 330
screen_width	Width of the device screen in pixels. Used in device profiling. Ex- 1920
screen_height	Height of the device screen in pixels. Ex- 1080

Successful Response

If all the details are correct you'll get a 202 response with staus as Pending

{\n    \"status\": \"pending\",\n    \"callback_url\": \"https://app.paybomb.tech/payment/63bd0bf80fb42a076e8a4dd1/\",\n    \"method\": \"GET\"\n}\n\n

If the response code is 202, after receiving the response body, direct the customer to the callback_url provided in the response.

Errors

If there are any errors then it'll be in the format of :

{\n    \"message\": \"descriptive error message\",\n    \"code\": \"error_code\"\n}\n\n

Please see the Status Code section for further details.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Error Messages
Client Ip could not be matched with Merchant Ip
Invalid Card Information
Card is Blocked
Different Type of key used to create purchase and payment
You charges setting is incomplete .Plese Contact to adminstrartor.
Allowed Attempt for this Transaction has been consumed
Invalid Card Expiry(Valid Format:MM/YY) must be greator than current month/year
Customer profile is Blocked
Customer/Card not allowed for transaction

","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"55300479-5b71-4b30-84e2-5ba8021bff9c","id":"55300479-5b71-4b30-84e2-5ba8021bff9c","name":"APIs","type":"folder"}},"urlObject":{"path":["p","64bff4fff63e36669499e9c8",""],"host":["https://app.paybomb.tech/api/v1"],"query":[{"key":"s2s","value":"true"}],"variable":[]}},"response":[{"id":"64334509-500e-4a66-b587-0112e8faeb2a","name":"Success","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"cardholder_name\": \"dk\",\r\n \"card_number\": \"411111111111111\",\r\n \"expires\": \"10/23\",\r\n \"cvc\": \"345\",\r\n \"remember_card\": \"on\",\r\n \"remote_ip\": \"157.38.242.7\",\r\n \"user_agent\": \"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36\",\r\n \"accept_header\": \"text/html\",\r\n \"language\": \"en-US\",\r\n \"java_enabled\": false,\r\n \"javascript_enabled\": true,\r\n \"color_depth\": 24,\r\n \"utc_offset\": 0,\r\n \"screen_width\": 1920,\r\n \"screen_height\": 1080\r\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://app.paybomb.tech/api/v1/p/64bff4fff63e36669499e9c8/?s2s=true","host":["https://app.paybomb.tech/api/v1"],"path":["p","64bff4fff63e36669499e9c8",""],"query":[{"key":"s2s","value":"true"}]}},"status":"Accepted","code":202,"_postman_previewlanguage":"json","header":[{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"1; mode=block"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"X-Frame-Options","value":"DENY"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Date","value":"Thu, 13 Jul 2023 17:31:55 GMT"},{"key":"Keep-Alive","value":"timeout=60"},{"key":"Connection","value":"keep-alive"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": \"pending\",\n \"callback_url\": \"http://18.214.100.20/api/v1/payment/64b034ecc6dccf7d329d9eb3/\",\n \"method\": \"GET\"\n}"},{"id":"904b5b83-d52d-4ddb-8096-86aa1cccf611","name":"Failure","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer Token","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"cardholder_name\": \"dk\",\r\n \"card_number\": \"4111111111111111\",\r\n \"expires\": \"10/23\",\r\n \"cvc\": \"345\",\r\n \"remember_card\": \"on\",\r\n \"remote_ip\": \"157.38.242.7\",\r\n \"user_agent\": \"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36\",\r\n \"accept_header\": \"text/html\",\r\n \"language\": \"en-US\",\r\n \"java_enabled\": false,\r\n \"javascript_enabled\": true,\r\n \"color_depth\": 24,\r\n \"utc_offset\": 0,\r\n \"screen_width\": 1920,\r\n \"screen_height\": 1080\r\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://app.paybomb.tech/api/v1/p/64bff4fff63e36669499e9c8/?s2s=true","host":["https://app.paybomb.tech/api/v1"],"path":["p","64bff4fff63e36669499e9c8",""],"query":[{"key":"s2s","value":"true"}]}},"status":"Unauthorized","code":401,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Tue, 06 Jan 2026 05:57:10 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"X-Frame-Options","value":"ALLOW-FROM *"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"x-session-id","value":"cc434220-0bcd-42c7-9078-53503b81a221"},{"key":"Vary","value":"Origin"},{"key":"Vary","value":"Access-Control-Request-Method"},{"key":"Vary","value":"Access-Control-Request-Headers"},{"key":"Server","value":"cloudflare"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"0"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"Strict-Transport-Security","value":"max-age=31536000 ; includeSubDomains"},{"key":"X-Cache","value":"Error from cloudfront"},{"key":"Via","value":"1.1 9bce423254194c16408d5cf7234126e2.cloudfront.net (CloudFront)"},{"key":"X-Amz-Cf-Pop","value":"IAD61-P10"},{"key":"X-Amz-Cf-Id","value":"FgTt6KEGIk0CH79DQDOvB1tYb1pGfaz0ryIVmQ0CCpDShyhsJGuAkA=="},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=9SnHJOEjnd1y7hArGsRLWmrk8H9ExaiR%2Fc%2BQMWhAvHlNPYCNEjS60wTjIyODXpca0ZD9%2BalkhLJ63boMGg%2B8iI6eFtXfW%2BxwGaBP1p1ZcwpA\"}]}"},{"key":"CF-RAY","value":"9b98f9f4684505e7-IAD"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"Authorization header missing\",\n \"code\": \"authentication_failed\"\n}"}],"_postman_id":"38a27849-024f-4407-83e2-744ba0d22dce"},{"name":"Capture","id":"e1f56021-389d-4b20-9f93-1052f6819960","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer Token"}],"body":{"mode":"raw","raw":"{\n \"merchant_reference\": \"64534345\"\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/purchases/69cd26b053d7b783ebf6b6e9/capture","description":"

After a successful pre-authorisation, use this endpoint to capture (settle) the held funds. You may capture the full authorised amount or a partial amount.

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"55300479-5b71-4b30-84e2-5ba8021bff9c","id":"55300479-5b71-4b30-84e2-5ba8021bff9c","name":"APIs","type":"folder"}},"urlObject":{"path":["purchases","69cd26b053d7b783ebf6b6e9","capture"],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"eaccef30-8310-4459-9a3d-bdbca93b7667","name":"Capture","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer Token"}],"body":{"mode":"raw","raw":"{\n \"merchant_reference\": \"64534345\"\n}","options":{"raw":{"language":"json"}}},"url":"https://app.paybomb.tech/api/v1/purchases/69cd26b053d7b783ebf6b6e9/capture"},"status":"Internal Server Error","code":500,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Wed, 01 Apr 2026 17:16:51 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"X-Frame-Options","value":"ALLOW-FROM *"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"x-session-id","value":"72818dba-381a-449a-8351-390453ddbf72"},{"key":"Vary","value":"Origin"},{"key":"Vary","value":"Access-Control-Request-Method"},{"key":"Vary","value":"Access-Control-Request-Headers"},{"key":"Server","value":"cloudflare"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"0"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"Strict-Transport-Security","value":"max-age=31536000 ; includeSubDomains"},{"key":"X-Cache","value":"Error from cloudfront"},{"key":"Via","value":"1.1 3578d122de1401ebc52a7afd35dd5d0c.cloudfront.net (CloudFront)"},{"key":"X-Amz-Cf-Pop","value":"IAD61-P10"},{"key":"X-Amz-Cf-Id","value":"zEG99N28vChcugkKEe-mJxhNgum-PAK1lcn_2mKqagcBd5deWquIjw=="},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=EnQbeJo0VkBTF%2BqefkY%2BZ1OejkL%2BkIkR76eA5%2FtL3qaxYlOL1ehFjmSIpGl5i91OldfFB41NXeRXp3E43WxFSEhlUj7OgOqbI6eYZs%2B%2BcUBdewUDmvk46tJrDA5WO53Bib8q\"}]}"},{"key":"CF-RAY","value":"9e593e77fb953ec9-IAD"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"purchaseId\": \"69cd361053d7b783ebf7324d\",\n \"client\": {\n \"customerId\": \"NA\",\n \"email\": \"kailashvishnoi126741@paybomb.tech\",\n \"full_name\": \"akshaya singhal\",\n \"date_of_birth\": \"1800-01-01\",\n \"street_address\": \"123\",\n \"country\": \"ZM\",\n \"city\": \"jaipur\",\n \"zip_code\": \"234567\",\n \"cc\": [],\n \"bcc\": [],\n \"stateCode\": \"CA\"\n },\n \"updated_on\": 1775056447,\n \"type\": \"purchase\",\n \"paymentMethod\": \"MASTER,VISA,VIRTUAL-IBAN,CRYPTO-WALLET,MAYA,GCASH,QRPH,BANKTRANSFER,NETBANKING,UPI-QR,PAYPLAY,UPI-INTENT,MOBILEMONEY,GOOGLEPAY,APPLEPAY\",\n \"amountUnit\": \"MAJOR\",\n \"errorMsg\": \"\",\n \"errorCode\": \"NA\",\n \"force_recurring\": false,\n \"created_on\": 1775056400,\n \"extraParam\": {\n \"aft\": {\n \"account_owner_address1\": \"test\",\n \"account_owner_address2\": \"test\",\n \"account_owner_street\": \"test\",\n \"account_owner_postal_code\": \"123\",\n \"account_owner_city\": \"test\",\n \"account_owner_country\": \"UK\",\n \"merchant_postal_code\": \"123\",\n \"merchant_state\": \"FRA\",\n \"acceptor_legal_name\": \"test\",\n \"sender_address\": \"test\",\n \"sender_city\": \"test\",\n \"sender_state\": \"RJ\",\n \"sender_country\": \"FRA\",\n \"sender_name\": \"test\",\n \"sender_account_number\": \"test\",\n \"recipient_name\": \"test\",\n \"bai\": \"AA\"\n }\n },\n \"merchantRef\": \"69cd361053d7b783ebf7324d\",\n \"purchase\": {\n \"currency\": \"EUR\",\n \"products\": [\n {\n \"name\": \"gaming cards\",\n \"quantity\": 1.0,\n \"price\": 10.0,\n \"discount\": 0,\n \"tax_percent\": \"0.00\"\n }\n ],\n \"total\": 10.0,\n \"requestAmount\": 10.0,\n \"language\": \"en\",\n \"notes\": \"\",\n \"debt\": 0,\n \"total_formatted\": 1.0,\n \"taxAmount\": 0.0,\n \"taxPercent\": 0.0,\n \"request_client_details\": [],\n \"email_message\": \"\"\n },\n \"payment\": {\n \"is_outgoing\": false,\n \"payment_type\": \"PURCHASE\",\n \"amount\": 10.0,\n \"currency\": \"EUR\",\n \"net_amount\": 10.0,\n \"fee_amount\": 0.0,\n \"pending_amount\": 0.0,\n \"pending_unfreeze_on\": null,\n \"description\": \"\",\n \"paid_on\": 1775056410,\n \"remote_paid_on\": 1775056410\n },\n \"issuer_details\": {\n \"website\": \"\",\n \"legal_street_address\": \"\",\n \"legal_country\": \"\",\n \"legal_city\": \"\",\n \"legal_zip_code\": \"\",\n \"bank_accounts\": [\n {}\n ],\n \"legal_name\": \"ECOMTEST1\",\n \"brand_name\": \"ECOMTEST1\",\n \"registration_number\": \"\",\n \"tax_number\": \"\"\n },\n \"transaction_data\": {\n \"payment_method\": \"\",\n \"flow\": \"payform\",\n \"extra\": {\n \"expiry_month\": \"12\",\n \"amount\": 10.0,\n \"card_issuer\": \"ING BELGIUM, S.A.\",\n \"masked_pan\": \"46401701****6658\",\n \"card_brand\": \"VISA\",\n \"card_issuer_country\": \"BE\",\n \"card_type\": \"CREDIT\",\n \"cardholder_name\": \"Sank\",\n \"expiry_year\": \"28\"\n },\n \"country\": \"\",\n \"attempts\": [\n {\n \"client_ip\": \"223.235.99.134\",\n \"type\": \"execute\",\n \"payment_method\": \"VISA\",\n \"flow\": \"payform\",\n \"successful\": true,\n \"country\": \"BE\",\n \"processing_time\": 1775056410,\n \"extra\": {\n \"expiry_month\": \"12\",\n \"amount\": 10.0,\n \"card_issuer\": \"ING BELGIUM, S.A.\",\n \"masked_pan\": \"46401701****6658\",\n \"card_brand\": \"VISA\",\n \"card_issuer_country\": \"BE\",\n \"card_type\": \"CREDIT\",\n \"cardholder_name\": \"Sank\",\n \"expiry_year\": \"28\"\n }\n }\n ]\n },\n \"status\": \"PAID\",\n \"status_history\": [\n {\n \"status\": \"created\",\n \"timestamp\": 1775056400\n },\n {\n \"status\": \"pending_execute\",\n \"timestamp\": 1775056410\n },\n {\n \"status\": \"payment_in_process\",\n \"timestamp\": 1775056410\n },\n {\n \"status\": \"3DS success\",\n \"timestamp\": 1775056424\n },\n {\n \"status\": \"preauthorized\",\n \"timestamp\": 1775056428\n },\n {\n \"status\": \"capture_in_process\",\n \"timestamp\": 1775056447\n },\n {\n \"status\": \"paid\",\n \"timestamp\": 1775056447\n }\n ],\n \"is_test\": false,\n \"brand_id\": \"bab077d5-df4d-4fda-8c6c-2f78d97c9a16\",\n \"send_receipt\": false,\n \"is_recurring_token\": false,\n \"skip_capture\": true,\n \"reference_generated\": \"PS1673\",\n \"issued\": \"2026-04-01\",\n \"due\": 1775056400,\n \"refund_upto\": 1776089649,\n \"cc_descriptor\": \"\",\n \"fraudScore\": \"NA\",\n \"trustScore\": \"NA\",\n \"extraFee\": \"0\",\n \"pix_payload\": {},\n \"payInDetails\": {},\n \"paidOn\": 1775056449,\n \"receivedAmt\": 0.0,\n \"captureTxns\": [\n {\n \"captureId\": \"41e31f9f-1e98-4f4d-b48c-7d1ed488fc3f\",\n \"purchaseId\": \"69cd361053d7b783ebf7324d\",\n \"amount\": 10.0,\n \"fxAmount\": 10.0,\n \"status\": \"PAID\",\n \"pspReference\": null,\n \"merchantReference\": \"64534345\",\n \"createdAt\": 1775056447,\n \"updatedAt\": 1775056447,\n \"whiteId\": 0,\n \"fxCurrency\": \"EUR\",\n \"bankMid\": \"payneticsexternal3ds\",\n \"isTest\": false,\n \"currency\": \"EUR\",\n \"amountInUsd\": 11.85,\n \"merchantName\": \"KailashMerchant\",\n \"bankName\": \"paynatics-aft_\",\n \"bankId\": \"532\",\n \"trxMethod\": \"CARDS\",\n \"rollingReserve\": 0.0,\n \"transFees\": 0.0,\n \"mdr\": 0.0,\n \"isSettlementPending\": 0,\n \"parentId\": 0,\n \"transSettlementId\": null,\n \"errorSettlementId\": null,\n \"merchantId\": \"589\"\n }\n ],\n \"taxAmount\": 0.0,\n \"surcharge\": 0.0,\n \"surchargeType\": \"\",\n \"sessionId\": \"\",\n \"refund_availability\": \"NONE\",\n \"refundable_amount\": 10.0,\n \"success_redirect\": \"https://google.com/getResponse.jsp?issucces=true\",\n \"failure_redirect\": \"https://google.com/getResponse.jsp?issucces=false\",\n \"cancel_redirect\": \"\",\n \"success_callback\": \"https://www.google.com/\",\n \"failure_callback\": \"https://app.paybomb.tech/merchant\",\n \"platform\": \"API\",\n \"created_from_ip\": \"223.235.99.134\",\n \"checkout_url\": \"https://app.paybomb.tech/payments/47395a8217d29014a4af6b1c494ac06b/\",\n \"direct_post_url\": \"https://app.paybomb.tech/api/v1/p/69cd361053d7b783ebf7324d/\",\n \"payoutProcess\": false\n}"}],"_postman_id":"e1f56021-389d-4b20-9f93-1052f6819960"},{"name":"Cancel","id":"a9e6b414-35b0-4497-8767-be77ce7a6949","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer 309855a6e22c2bc9873f11ee5997cb3ff246a8e8ec4f009f2924ad7178b2ad7b"}],"url":"https://app.paybomb.tech/api/v1/purchases/69ca76dbace4fa4413db928c/cancel","description":"

Use this endpoint to cancel an authorised payment before it has been captured. Voiding releases the held funds back to the customer immediately.

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"55300479-5b71-4b30-84e2-5ba8021bff9c","id":"55300479-5b71-4b30-84e2-5ba8021bff9c","name":"APIs","type":"folder"}},"urlObject":{"path":["purchases","69ca76dbace4fa4413db928c","cancel"],"host":["https://app.paybomb.tech/api/v1"],"query":[],"variable":[]}},"response":[{"id":"e00f5d8e-b3aa-43f1-aa19-7decf4fd329e","name":"Cancel","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Bearer 309855a6e22c2bc9873f11ee5997cb3ff246a8e8ec4f009f2924ad7178b2ad7b"}],"url":"https://app.paybomb.tech/api/v1/purchases/69ca76dbace4fa4413db928c/cancel"},"status":"Method Not Allowed","code":405,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Wed, 01 Apr 2026 17:18:25 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"X-Frame-Options","value":"ALLOW-FROM *"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"x-session-id","value":"1c9b7d67-8dec-4e71-b35b-7952f23b67ed"},{"key":"Vary","value":"Origin"},{"key":"Vary","value":"Access-Control-Request-Method"},{"key":"Vary","value":"Access-Control-Request-Headers"},{"key":"Server","value":"cloudflare"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"0"},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"Expires","value":"0"},{"key":"Strict-Transport-Security","value":"max-age=31536000 ; includeSubDomains"},{"key":"X-Cache","value":"Error from cloudfront"},{"key":"Via","value":"1.1 8bd3b44b8e417f2b75cd6e631907112a.cloudfront.net (CloudFront)"},{"key":"X-Amz-Cf-Pop","value":"IAD61-P10"},{"key":"X-Amz-Cf-Id","value":"WSuVRaHm9E64itnjsFWAyBSPCR8YOFpZr7jY-NAhT-Ae-3_bc-hNTw=="},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=%2FOrvZsMz3WoHOQDEvKgGSADamNtnaGrILftqtr5BiqYIlUvgXZT89lPPwyXtpIDJW8BNOXjG%2FgAQmYnOUsUpQZ%2BDIVJsSDsxo4FxOEgIKcxPYcG21xgzcTNpNqbnk%2Fnw%2FEki\"}]}"},{"key":"CF-RAY","value":"9e5940bd580a07ed-IAD"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"purchaseId\": \"69cd36c353d7b783ebf743e9\",\n \"client\": {\n \"customerId\": \"NA\",\n \"email\": \"kailashvishnoi126741@paybomb.tech\",\n \"full_name\": \"akshaya singhal\",\n \"date_of_birth\": \"1800-01-01\",\n \"street_address\": \"123\",\n \"country\": \"ZM\",\n \"city\": \"jaipur\",\n \"zip_code\": \"234567\",\n \"cc\": [],\n \"bcc\": [],\n \"stateCode\": \"CA\"\n },\n \"updated_on\": 1775056649,\n \"type\": \"purchase\",\n \"paymentMethod\": \"MASTER,VISA,VIRTUAL-IBAN,CRYPTO-WALLET,MAYA,GCASH,QRPH,BANKTRANSFER,NETBANKING,UPI-QR,PAYPLAY,UPI-INTENT,MOBILEMONEY,GOOGLEPAY,APPLEPAY\",\n \"amountUnit\": \"MAJOR\",\n \"errorMsg\": \"\",\n \"errorCode\": \"NA\",\n \"force_recurring\": false,\n \"created_on\": 1775056579,\n \"extraParam\": {\n \"aft\": {\n \"account_owner_address1\": \"test\",\n \"account_owner_address2\": \"test\",\n \"account_owner_street\": \"test\",\n \"account_owner_postal_code\": \"123\",\n \"account_owner_city\": \"test\",\n \"account_owner_country\": \"UK\",\n \"merchant_postal_code\": \"123\",\n \"merchant_state\": \"FRA\",\n \"acceptor_legal_name\": \"test\",\n \"sender_address\": \"test\",\n \"sender_city\": \"test\",\n \"sender_state\": \"RJ\",\n \"sender_country\": \"FRA\",\n \"sender_name\": \"test\",\n \"sender_account_number\": \"test\",\n \"recipient_name\": \"test\",\n \"bai\": \"AA\"\n }\n },\n \"merchantRef\": \"69cd36c353d7b783ebf743e9\",\n \"purchase\": {\n \"currency\": \"EUR\",\n \"products\": [\n {\n \"name\": \"gaming cards\",\n \"quantity\": 1.0,\n \"price\": 10.0,\n \"discount\": 0,\n \"tax_percent\": \"0.00\"\n }\n ],\n \"total\": 10.0,\n \"requestAmount\": 10.0,\n \"language\": \"en\",\n \"notes\": \"\",\n \"debt\": 0,\n \"total_formatted\": 1.0,\n \"taxAmount\": 0.0,\n \"taxPercent\": 0.0,\n \"request_client_details\": [],\n \"email_message\": \"\"\n },\n \"payment\": {\n \"is_outgoing\": false,\n \"payment_type\": \"PURCHASE\",\n \"amount\": 10.0,\n \"currency\": \"EUR\",\n \"net_amount\": 10.0,\n \"fee_amount\": 0.0,\n \"pending_amount\": 0.0,\n \"pending_unfreeze_on\": null,\n \"description\": \"\",\n \"paid_on\": 1775056600,\n \"remote_paid_on\": 1775056600\n },\n \"issuer_details\": {\n \"website\": \"\",\n \"legal_street_address\": \"\",\n \"legal_country\": \"\",\n \"legal_city\": \"\",\n \"legal_zip_code\": \"\",\n \"bank_accounts\": [\n {}\n ],\n \"legal_name\": \"ECOMTEST1\",\n \"brand_name\": \"ECOMTEST1\",\n \"registration_number\": \"\",\n \"tax_number\": \"\"\n },\n \"transaction_data\": {\n \"payment_method\": \"\",\n \"flow\": \"payform\",\n \"extra\": {\n \"expiry_month\": \"12\",\n \"amount\": 10.0,\n \"card_issuer\": \"JPMORGAN CHASE BANK, N.A.\",\n \"masked_pan\": \"42000000****0000\",\n \"card_brand\": \"VISA\",\n \"card_issuer_country\": \"US\",\n \"card_type\": \"CREDIT\",\n \"cardholder_name\": \"Sank\",\n \"expiry_year\": \"28\"\n },\n \"country\": \"\",\n \"attempts\": [\n {\n \"client_ip\": \"223.235.99.134\",\n \"type\": \"execute\",\n \"payment_method\": \"VISA\",\n \"flow\": \"payform\",\n \"successful\": true,\n \"country\": \"US\",\n \"processing_time\": 1775056600,\n \"extra\": {\n \"expiry_month\": \"12\",\n \"amount\": 10.0,\n \"card_issuer\": \"JPMORGAN CHASE BANK, N.A.\",\n \"masked_pan\": \"42000000****0000\",\n \"card_brand\": \"VISA\",\n \"card_issuer_country\": \"US\",\n \"card_type\": \"CREDIT\",\n \"cardholder_name\": \"Sank\",\n \"expiry_year\": \"28\"\n }\n }\n ]\n },\n \"status\": \"CANCELLED\",\n \"status_history\": [\n {\n \"status\": \"created\",\n \"timestamp\": 1775056579\n },\n {\n \"status\": \"pending_execute\",\n \"timestamp\": 1775056600\n },\n {\n \"status\": \"payment_in_process\",\n \"timestamp\": 1775056600\n },\n {\n \"status\": \"3DS success\",\n \"timestamp\": 1775056607\n },\n {\n \"status\": \"preauthorized\",\n \"timestamp\": 1775056611\n },\n {\n \"status\": \"void_in_process\",\n \"timestamp\": 1775056632\n },\n {\n \"status\": \"preauthorized\",\n \"timestamp\": 1775056632\n },\n {\n \"status\": \"void_in_process\",\n \"timestamp\": 1775056647\n },\n {\n \"status\": \"cancelled\",\n \"timestamp\": 1775056649\n }\n ],\n \"is_test\": false,\n \"brand_id\": \"bab077d5-df4d-4fda-8c6c-2f78d97c9a16\",\n \"send_receipt\": false,\n \"is_recurring_token\": false,\n \"skip_capture\": true,\n \"reference_generated\": \"PS1675\",\n \"issued\": \"2026-04-01\",\n \"due\": 1775056579,\n \"refund_upto\": 1776089849,\n \"cc_descriptor\": \"\",\n \"fraudScore\": \"NA\",\n \"trustScore\": \"NA\",\n \"extraFee\": \"0\",\n \"pix_payload\": {},\n \"payInDetails\": {},\n \"paidOn\": 0,\n \"receivedAmt\": 0.0,\n \"taxAmount\": 0.0,\n \"surcharge\": 0.0,\n \"surchargeType\": \"\",\n \"sessionId\": \"\",\n \"refund_availability\": \"NONE\",\n \"refundable_amount\": 10.0,\n \"success_redirect\": \"https://google.com/getResponse.jsp?issucces=true\",\n \"failure_redirect\": \"https://google.com/getResponse.jsp?issucces=false\",\n \"cancel_redirect\": \"\",\n \"success_callback\": \"https://www.google.com/\",\n \"failure_callback\": \"https://app.paybomb.tech/merchant\",\n \"platform\": \"API\",\n \"created_from_ip\": \"223.235.99.134\",\n \"checkout_url\": \"https://app.paybomb.tech/payments/23182fc42998cb02b4a3e6aa5c3e26c8/\",\n \"direct_post_url\": \"https://app.paybomb.tech/api/v1/p/69cd36c353d7b783ebf743e9/\",\n \"payoutProcess\": false\n}"}],"_postman_id":"a9e6b414-35b0-4497-8767-be77ce7a6949"}],"id":"55300479-5b71-4b30-84e2-5ba8021bff9c","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"faa83157-7798-4a6c-9122-cab04cc92898"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"1b4d8940-8958-4661-82c1-3ad7914b49bd"}}],"_postman_id":"55300479-5b71-4b30-84e2-5ba8021bff9c","description":""},{"name":"Transaction Status Lifecycle","item":[],"id":"7e038849-ad8d-4427-99d0-d39d5b445d25","description":"

Every payment processed through the pre-authorisation flow passes through a series of statuses. Understanding these statuses is critical for building robust integrations.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Description	Available Actions
CREATED	Transactions are initiated by merchants.	Open checkout url
PENDING_EXECUTE	Transaction is in processing	Wait
PAYMENT_IN_PROCESS	Transaction is being processed by the payment network.	Wait
PREAUTHORIZED	Funds have been successfully held. Ready for capture or void.	Capture, Void
CAPTURE_IN_PROCESS	Capture has been inititated and is in process.	Wait
PAID	Full authorised amount has been settled to the merchant.	Refund, Partial Refund
PARTIALLY_CAPTURED	A portion of the authorised amount was captured. Remainder released.	Refund (on captured amount), Partial Refund
VOID_IN_PROCESS	Authorisation was cancelled before capture and it is in process	None
CANCELLED	Authorisation was cancelled before capture. Funds released.	None
EXPIRED	Authorisation expired without capture. Funds auto-released.	None
ERROR	A processing error occurred during the preauthorisation step	Retry Preauth
REFUNDED	Post-capture return of funds (separate API).	None
PARTIAL_REFUNDED	Post-capture return of partial funds (separate API).	Partial Refund

","_postman_id":"7e038849-ad8d-4427-99d0-d39d5b445d25"},{"name":"Best Practices","item":[],"id":"7b5da023-1820-4d82-b3e7-7ad47738dbf4","description":"

Capture Timing

Capture payments as soon as the goods are shipped or the service is delivered. The longer you wait, the higher the risk of authorisation expiry, customer disputes, and declined captures.

Idempotency

Always include the X-Idempotency-Key header for all write operations (authorise, capture, void). This protects against duplicate transactions caused by network timeouts or retries.

Webhook-Driven Architecture

Do not rely solely on synchronous API responses for business logic. Implement webhook handlers to receive real-time status updates and use them as the source of truth for transaction state in your system.

Error Handling

Implement retry logic with exponential backoff for 5xx errors and 429 (rate limit) responses. For 4xx errors, parse the error response body and handle each error code appropriately in your application logic.

PCI Compliance

If you are handling raw card numbers, you must be PCI DSS Level 1 certified. Paybomb strongly recommends using tokenised payment methods to minimise your PCI scope. Use the Paybomb Cashier or client-side SDK to tokenise card details before they reach your server.

Reconciliation

Use the reference field on authorise, capture, and void requests to associate Paybomb transactions with your internal order system. The balances object in every response provides a real-time breakdown for reconciliation.

3D Secure

Enable 3DS for all pre-authorisation requests where supported. This shifts fraud liability to the card issuer and reduces chargebacks. Paybomb supports 3DS 2.x with frictionless and challenge flows.

Q: Can I capture more than the authorised amount?

A: No. The capture amount must be less than or equal to the authorised amount. If you need to charge more, you must create a new authorisation for the additional amount.

Q: Can I perform multiple partial captures on a single authorisation?

A: Yes. Paybomb supports multiple captures per authorisation. But you will need to contact the support team for enabling the same.

Q: What happens if I do not capture before the authorisation expires?

A: The authorisation automatically expires and the held funds are released back to the customer. You will receive a payment.expired webhook event. You must create a new authorisation to charge the customer.

Q: Can I void a payment after it has been captured?

A: No. Once a payment is captured, you must use the Refund API to return funds. The void endpoint only works for payments in AUTHORISED status.

Q: How long does a void take to reflect on the customer’s statement?

A: Typically, the hold is removed within 1–3 business days, depending on the issuing bank. Some banks may take up to 7 days to release the hold.

Q: Does the customer see the pre-authorisation on their statement?

A: Yes. The customer will see a pending charge for the authorised amount. This pending charge is released upon void or expiry, or replaced by the final charge upon capture.

Q: Can I use pre-authorisation with non-card payment methods?

A: Pre-authorisation is primarily supported for card payments. Support for alternative payment methods varies. Check the Paybomb payment methods documentation for details.

Q: Is 3D Secure required for pre-authorisations?

A: 3DS is not required but is strongly recommended. It reduces fraud liability and chargeback risk. Paybomb supports 3DS on all card pre-authorisation requests.

\n","_postman_id":"80d1a733-27c9-44ce-8558-5dcb783020cc"}],"id":"a48dd8ee-4749-4c27-a6ed-b483807a1fef","description":"

Overview

Pre-authorisation (also known as \"auth only\") is a two-step payment process where a merchant first reserves (holds) funds on a customer’s payment method without immediately capturing the amount. This allows the merchant to verify fund availability before fulfilling an order, then capture (settle) the payment at a later time — or void (cancel) the hold if the order is not fulfilled.

When to Use Pre-Authorisation

Pre-authorisation is ideal for scenarios where the final transaction amount may change, or where goods/services are not delivered immediately. Common use cases include:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Use Case	Description
E-Commerce	Authorise at checkout; capture when the order ships. Void if the item is out of stock.
Hospitality	Pre-authorise the estimated room charge at check-in; adjust and capture at checkout.
Car Rentals	Hold the estimated rental cost; capture the final amount upon vehicle return.
Subscriptions	Verify the card with a pre-auth before activating a trial; capture when billing begins.
Marketplaces	Authorise the buyer’s funds; capture once the seller confirms dispatch.

Key Concepts

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Term	Definition
Pre-Authorisation	A transaction that reserves funds on the customer’s card without settling them. Also called \"auth only\" or \"manual capture\".
Capture	The action of claiming the previously authorised funds. Can be full or partial.
Partial Capture	Capturing less than the originally authorised amount. The remaining balance is automatically released.
Void	Cancelling a pre-authorised transaction before capture, releasing the held funds back to the customer.
Authorisation Expiry	The time window during which a pre-auth remains valid. Typically 7–30 days depending on card scheme and MCC.

","_postman_id":"a48dd8ee-4749-4c27-a6ed-b483807a1fef"},{"name":"Get Balance API (V2) - Orchestration","item":[{"name":"Checking Balance","id":"b3aaacf3-5f45-48ed-bed2-91e35a8aa207","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer Token","type":"text"}],"body":{"mode":"raw","raw":"{ \r\n \"paymentMethod\" : \"PAYOUT-INTERAC-ETRANSFER\"\r\n\r\n}\r\n","options":{"raw":{"language":"json"}}},"url":"/getBalance","description":"

API for checking available balance

URL :- /getBalance/
\n
RequestType: POST
\n
Request Body
\n

Note: Currency is not a mandatory parameter. If no parameter is specified then all respective currency balances would be provided, if any specific currency parameter is provided then only that currency balance would be provided.

\n","urlObject":{"path":["getBalance"],"host":[""],"query":[],"variable":[]}},"response":[{"id":"08022b58-f579-4ed3-90e8-31da9e95be42","name":"Checking Balance payout-success","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{ \r\n \"paymentMethod\" : \"PAYOUT-INTERAC-ETRANSFER\"\r\n}\r\n","options":{"raw":{"language":"json"}}},"url":"/getBalance"},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"paymentMethod\": \"PAYOUT-INTERAC-ETRANSFER\",\n \"status\": \"success\",\n \"gateways\": [\n {\n \"gatewayName\": \"payhost\",\n \"status\": \"success\",\n \"error\": null,\n \"balances\": [\n {\n \"currency\": \"CAD\",\n \"balance\": 808.380000\n },\n {\n \"currency\": \"USD\",\n \"balance\": 803.380000\n }\n ]\n },\n {\n \"gatewayName\": \"choicepaypg\",\n \"status\": \"success\",\n \"error\": null,\n \"balances\": [\n {\n \"currency\": \"CAD\",\n \"balance\": 808.380000\n },\n {\n \"currency\": \"USD\",\n \"balance\": 808.380000\n }\n ]\n }\n ],\n \"aggregatedBalances\": [\n {\n \"currency\": \"CAD\",\n \"balance\": 1616.760000\n },\n {\n \"currency\": \"USD\",\n \"balance\": 1611.760000\n }\n ]\n}"},{"id":"94f626ca-13e7-4326-a5ea-dc88d4d39f23","name":"Checking Balance partial-success","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{ \r\n \"paymentMethod\" : \"CARDS\"\r\n}\r\n","options":{"raw":{"language":"json"}}},"url":"/getBalance"},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"paymentMethod\": \"CARDS\",\n \"status\": \"partial\",\n \"gateways\": [\n {\n \"gatewayName\": \"a55Mandate\",\n \"status\": \"failed\",\n \"error\": {\n \"code\": \"error\",\n \"message\": \"Bank does not provide balance\"\n },\n \"balances\": []\n },\n {\n \"gatewayName\": \"bk_sbx_smilepayz_pix_payin\",\n \"status\": \"success\",\n \"error\": null,\n \"balances\": [\n {\n \"currency\": \"IDR\",\n \"balance\": 250000.000000\n }\n ]\n },\n {\n \"gatewayName\": \"choicepay_pg\",\n \"status\": \"success\",\n \"error\": null,\n \"balances\": [\n {\n \"currency\": \"AED\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"AUD\",\n \"balance\": 3412.000000\n },\n {\n \"currency\": \"BRL\",\n \"balance\": 100.089996\n },\n {\n \"currency\": \"BTC\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"BXC\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"CAD\",\n \"balance\": 1000.000000\n },\n {\n \"currency\": \"CDF\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"COP\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"DKK\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"EGP\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"ETH\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"EUR\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"GBP\",\n \"balance\": -24.327801\n },\n {\n \"currency\": \"GHS\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"IDR\",\n \"balance\": 1000.000000\n },\n {\n \"currency\": \"INR\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"JPY\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"KES\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"MWK\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"MXN\",\n \"balance\": -4.770000\n },\n {\n \"currency\": \"NGN\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"NZD\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"RWF\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"THB\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"TZS\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"UGX\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"USD\",\n \"balance\": 167.457992\n },\n {\n \"currency\": \"USDC\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"USDT\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"UZS\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"XAF\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"XOF\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"ZAR\",\n \"balance\": 120.000000\n },\n {\n \"currency\": \"ZMW\",\n \"balance\": 0.000000\n }\n ]\n },\n {\n \"gatewayName\": \"payhost\",\n \"status\": \"failed\",\n \"error\": {\n \"code\": \"error\",\n \"message\": \"Bank does not provide balance\"\n },\n \"balances\": []\n }\n ],\n \"aggregatedBalances\": [\n {\n \"currency\": \"AED\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"AUD\",\n \"balance\": 3412.000000\n },\n {\n \"currency\": \"BRL\",\n \"balance\": 100.089996\n },\n {\n \"currency\": \"BTC\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"BXC\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"CAD\",\n \"balance\": 1000.000000\n },\n {\n \"currency\": \"CDF\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"COP\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"DKK\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"EGP\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"ETH\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"EUR\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"GBP\",\n \"balance\": -24.327801\n },\n {\n \"currency\": \"GHS\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"IDR\",\n \"balance\": 251000.000000\n },\n {\n \"currency\": \"INR\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"JPY\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"KES\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"MWK\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"MXN\",\n \"balance\": -4.770000\n },\n {\n \"currency\": \"NGN\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"NZD\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"RWF\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"THB\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"TZS\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"UGX\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"USD\",\n \"balance\": 167.457992\n },\n {\n \"currency\": \"USDC\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"USDT\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"UZS\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"XAF\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"XOF\",\n \"balance\": 0.000000\n },\n {\n \"currency\": \"ZAR\",\n \"balance\": 120.000000\n },\n {\n \"currency\": \"ZMW\",\n \"balance\": 0.000000\n }\n ]\n}"},{"id":"accf24b9-4787-47af-8733-2888c01fada6","name":"Checking Balance payout-error","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{ \r\n \"paymentMethod\" : \"PAYOUT-INTERAC\"\r\n}\r\n","options":{"raw":{"language":"json"}}},"url":"/getBalance"},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"paymentMethod\": \"PAYOUT-INTERAC\",\n \"status\": \"failed\",\n \"gateways\": [\n {\n \"gatewayName\": \"payhost\",\n \"status\": \"failed\",\n \"error\": {\n \"code\": \"error\",\n \"message\": \"Bank does not provide balance\"\n },\n \"balances\": []\n }\n ],\n \"aggregatedBalances\": []\n}"}],"_postman_id":"b3aaacf3-5f45-48ed-bed2-91e35a8aa207"}],"id":"cbbd040c-a566-4e46-8723-5d480265592d","description":"

The Get Balance API (V2) provides orchestrator-level visibility into available balances across multiple payment methods and banking partners. This version enhances the existing balance API by aggregating and returning balance details for all supported payment methods associated with all the PSPs for the merchant

Overview

Purpose: Retrieve available balance information across different banks/payment methods.
\n
Scope: Orchestrator-level (not limited to a single merchant or payment method).
\n
Enhancement over previous version:
\n
- Returns balances for all payment methods linked to the orchestrator.
  \n
- Provides both consolidated and MID-level (Merchant ID) breakdowns.
  \n
\n

Request Parameters

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Type	Required	Description
paymentMethod	string	yes	Specifies the payment method to query. Example: \"PAYOUT-INTERAC-ETRANSFER\"

Behavior

When a valid paymentMethod is provided, the API retrieves:
\n
- Balance details across all associated banks/payment methods.
  \n
- MID-level breakdown for each bank.
  \n
- Consolidated balance per payment method.
  \n
\n
The API is designed specifically for orchestrators and returns aggregated data across multiple merchants and banking integrations.
\n

Success Response

On successful retrieval, the API returns:

Payment Method Details
\n
List of Banks / Payment Providers
\n
MID-Level Breakdown
\n
Consolidated Balance
\n

Error Handling

If balance details are not found or the request cannot be processed, the API returns:

Appropriate status code
\n
Error message
\n

\n","_postman_id":"cbbd040c-a566-4e46-8723-5d480265592d"}],"event":[{"listen":"prerequest","script":{"type":"text/javascript","requests":{},"exec":[""],"id":"8b1f3401-af7b-45d0-988a-f5b3f4aee8df"}},{"listen":"test","script":{"type":"text/javascript","requests":{},"exec":[""],"id":"90ca482f-8cbc-4a8b-8054-2714591e017e"}}],"variable":[{"key":"BaseURL","value":"https://app.paybomb.tech/api/v1"},{"key":"StagingAPIKey","value":""},{"key":"BaseV2URL","value":""}]}