Global Business Pay merchant API documentation
Integrate secure payment processing, card tokenization, cross-border transfers and merchant account management into your application.
https://api.globalbusinessspay.com/v2. Sandbox keys are prefixed
gbp_test_; production keys use gbp_live_.
Overview
The Global Business Pay Merchant API lets businesses and developers integrate payment processing directly into their applications, websites and platforms. It is built on RESTful principles with JSON data interchange.
Whether you are processing one-time payments, setting up recurring billing, tokenizing cards for future use, or managing cross-border transfers, the GBP API provides the toolkit you need with security at every layer.
Bank-grade security
256-bit SSL encryption, 3D Secure v2, tokenized card storage and real-time fraud monitoring.
Fast processing
Average API response time of 180 ms globally, with a 99.99% uptime target.
180+ countries
Accept payments from customers in 180+ countries across 135+ currencies.
API architecture
Authentication
All API requests must be authenticated using your unique Merchant API Key and Secret Key. These credentials are generated when your merchant account is approved and can be rotated at any time through the Merchant Dashboard.
Authentication uses HTTP Basic Auth. Send your API key as the username and the secret
key as the password in the Authorization header of every request. Requests
without valid authentication return 401 Unauthorized.
Authorization header
Authorization: Basic <base64(api_key:secret_key)>
X-GBP-API-Version: 2024-01-15
X-GBP-Request-ID: req_8f3a2b7c1d4e5f6a
Content-Type: application/jsoncURL example — authenticated request
curl -X GET "https://api.globalbusinessspay.com/v2/account" \
-u "gbp_live_sk_abc123def456ghi789":"" \
-H "X-GBP-API-Version: 2024-01-15" \
-H "X-GBP-Request-ID: req_$(uuidgen)"API key security best practices
- Never expose secret keys in client-side code, public repositories or browser-based applications. Use them only for server-to-server communication.
- Store credentials in environment variables instead of hardcoding them in source.
- Rotate secret keys regularly — every 90 days is recommended. Old keys remain valid for a 24-hour grace period.
- Configure IP whitelisting in the Merchant Dashboard to restrict API access to your own servers.
Base URLs & environments
GBP provides separate environments for development and production. Both maintain the same API contract.
| Environment | Base URL | Purpose |
|---|---|---|
| Sandbox | https://api.globalbusinessspay.com/v2 |
Development, testing and integration validation. No real money moves. |
| Production | https://api.globalbusinessspay.com/v2 |
Live transactions with real funds. Requires verified merchant status. |
| Webhook test | https://webhook-test.globalbusinessspay.com |
Simulate webhook events for local development. |
The sandbox mirrors production but processes simulated transactions. Sandbox keys are
prefixed gbp_test_ while production keys use gbp_live_. Using a
sandbox key on a production endpoint, or the reverse, returns 403 Forbidden.
Create payment
Initiate a new payment transaction. This endpoint supports one-time card payments, tokenized card charges, bank transfers (SEPA/SWIFT) and cryptocurrency payments. The response includes a unique transaction ID for tracking.
/v2/paymentsThe payment status starts as pending and moves to completed,
failed or requires_action for 3D Secure.
Request parameters
| Parameter | Type | Description |
|---|---|---|
amountRequired | integer | Payment amount in the smallest currency unit (cents). e.g. 5000 for $50.00. |
currencyRequired | string (3) | ISO 4217 currency code, e.g. USD, EUR, GBP. |
sourceRequired | object | Payment source: a card object, token ID or bank_transfer object. |
descriptionOptional | string (255) | Human-readable description shown on customer statements. |
customer_idOptional | string | Existing customer ID for repeat payments. Creates a new customer if omitted. |
metadataOptional | object | Key-value pairs (max 20 keys, 500 characters each) attached to the transaction. |
webhook_urlOptional | string | Override the default webhook URL for this transaction only. |
idempotency_keyOptional | string (100) | Prevents duplicate charges. The same key with the same parameters returns the same response for 24 hours. |
3d_secureOptional | boolean | Force 3D Secure authentication. Default: true for EU cards. |
captureOptional | boolean | If false, creates an authorised hold only and you capture later. Default: true. |
Request body — card payment
{
"amount": 25500000,
"currency": "USD",
"source": {
"type": "card",
"number": "4228567890123456",
"exp_month": 8,
"exp_year": 2029,
"cvc": "987",
"holder_name": "JOHN DOE"
},
"description": "World Card Activation - GBP Merchant",
"idempotency_key": "world_card_001_johndoe_20250424",
"3d_secure": true,
"metadata": { "card_type": "world" }
}Response — success (200 OK)
{
"id": "pay_9xK2mNpQr5sT7uVw",
"object": "payment",
"amount": 25500000,
"currency": "USD",
"status": "completed",
"source_type": "card",
"card_brand": "visa",
"card_last4": "3456",
"description": "World Card Activation - GBP Merchant",
"fee_amount": 38250,
"net_amount": 25461750,
"exchange_rate": 1.0000,
"3d_secure_status": "authenticated",
"risk_score": 12,
"metadata": { "card_type": "world" },
"created_at": "2026-04-24T14:32:18Z",
"receipt_url": "https://portal.globalbusinessspay.com/receipts/pay_9xK2mNpQr5sT7uVw"
}Retrieve payment
Fetch the details of an existing payment transaction using its unique ID. Use this endpoint to check payment status, view fee breakdowns, access receipt URLs and verify metadata.
/v2/payments/:payment_idPath parameters
| Parameter | Type | Description |
|---|---|---|
payment_idRequired | string | The payment ID returned from the create call. Format pay_xxxxxxxxxxxxxxxx. |
curl -X GET "https://api.globalbusinessspay.com/v2/payments/pay_9xK2mNpQr5sT7uVw" \
-u "gbp_live_sk_abc123def456ghi789":"" \
-H "X-GBP-API-Version: 2024-01-15"Process refund
Refund a previously completed payment, partially or in full. Refunds go to the original payment source and typically settle within 5–10 business days for card payments, and 1–2 days for bank transfers.
/v2/payments/:payment_id/refundsThe sum of all refunds cannot exceed the original payment amount.
Request parameters
| Parameter | Type | Description |
|---|---|---|
amountOptional | integer | Refund amount in cents. If omitted, the full payment amount is refunded. |
reasonOptional | string | One of requested_by_customer, duplicate, fraudulent, other. |
metadataOptional | object | Additional key-value data attached to the refund record. |
{
"amount": 500000,
"reason": "requested_by_customer",
"metadata": { "ticket_id": "SUPPORT-1024" }
}List transactions
Retrieve a paginated list of all transactions on your merchant account, filtered by date range, status, amount, currency or payment method.
/v2/payments?limit=50&status=completed&from=2026-04-01&to=2026-04-24Default limit is 25 and the maximum is 100. Results are sorted by created_at
descending.
Query parameters
| Parameter | Type | Description |
|---|---|---|
limit | integer | Results per page. Default 25, max 100. |
starting_after | string | Cursor for pagination: pass the last object ID to get the next page. |
status | string | Filter: pending, requires_action, completed, failed, refunded, disputed. |
from | string (date) | Start date filter in YYYY-MM-DD format. |
to | string (date) | End date filter in YYYY-MM-DD format. |
currency | string | Filter by ISO currency code. |
min_amount | integer | Only transactions with amount greater than or equal to this value, in cents. |
max_amount | integer | Only transactions with amount less than or equal to this value, in cents. |
Tokenize card
Store card details securely by converting them into a reusable token. Tokenized cards can be charged later without re-entering card details. Card data never touches your servers when you use GBP tokenization.
/v2/tokensThe card number is validated with the Luhn algorithm and real-time BIN checking before tokenization.
{
"card": {
"number": "4228567890123456",
"exp_month": 8,
"exp_year": 2029,
"cvc": "987",
"holder_name": "JOHN DOE",
"address_line1": "123 Financial District",
"address_city": "London",
"address_postal_code": "EC2N 1AR",
"address_country": "GB"
},
"validate_card": true
}Response — token created
{
"id": "tok_3bN5pQr7sT9uVxYz",
"object": "token",
"type": "card",
"card": {
"brand": "visa",
"last4": "3456",
"exp_month": 8,
"exp_year": 2029,
"holder_name": "JOHN DOE",
"funding": "debit",
"issuer_country": "GB",
"checks": {
"cvc_check": "pass",
"address_line1_check": "pass",
"postal_code_check": "pass"
}
},
"created_at": "2026-04-24T14:32:18Z"
}Charge token
Charge a previously created card token to enable one-click payments, subscription billing and saved-card workflows without storing sensitive card data on your servers.
/v2/paymentsUse a token ID as the payment source. The token must be valid and the associated card must not be expired or revoked.
{
"amount": 50000,
"currency": "USD",
"source": "tok_3bN5pQr7sT9uVxYz",
"description": "Monthly subscription - Premium Plan",
"customer_id": "cus_7aB3cDe4fGh5iJk6"
}Verify card
Perform a zero-amount authorisation to validate card details without charging the customer. Useful for account verification, card validity checks before storing tokens, and KYC workflows.
/v2/verifyPerforms a $0 authorisation (or a 1.00 local-currency hold that is immediately reversed) to validate card authenticity.
Merchant account info
Retrieve details about your merchant account including business profile, verification status, enabled features, API permissions and compliance status.
/v2/account{
"id": "mer_2cD4eFg6hIj8kLm0",
"object": "merchant",
"business_name": "Acme Technologies Ltd",
"status": "active",
"verification_status": "verified",
"merchant_tier": "enterprise",
"email": "finance@acmetech.com",
"default_currency": "USD",
"supported_currencies": ["USD", "EUR", "GBP", "JPY"],
"api_permissions": [
"payments:read", "payments:write",
"refunds:write", "tokens:write",
"webhooks:read", "webhooks:write"
],
"processing_fees": {
"domestic_card": "1.5% + $0.25",
"international_card": "2.9% + $0.25",
"bank_transfer_sepa": "0.5%",
"bank_transfer_swift": "1.0% + $15"
},
"compliance": {
"kyc_status": "approved",
"aml_screening": "passed",
"sanctions_check": "cleared"
},
"created_at": "2020-03-15T09:22:00Z"
}Check balance
Retrieve real-time balance information across all supported currencies, including available balance, pending balance (funds in clearing) and reserved balance held for disputes or chargebacks.
/v2/balance{
"object": "balance",
"balances": [
{ "currency": "USD", "available": 125489500, "pending": 1842000, "reserved": 250000 },
{ "currency": "EUR", "available": 89245000, "pending": 756000, "reserved": 120000 }
],
"livemode": true,
"updated_at": "2026-04-24T14:32:18Z"
}Withdraw funds
Transfer available balance to an external bank account. Supports SEPA transfers (EUR, 1–2 business days), SWIFT transfers (global, 2–5 business days) and same-day wire for USD to US-based accounts.
/v2/transfersRequest parameters
| Parameter | Type | Description |
|---|---|---|
amountRequired | integer | Withdrawal amount in the smallest currency unit. |
currencyRequired | string (3) | Currency code. Must match the available balance currency. |
destinationRequired | object | Bank account object: account_number, routing_number or swift_bic, bank_name, country. |
referenceOptional | string | Internal reference visible on the bank statement. |
scheduleOptional | string | immediate or next_business_day. Default: immediate. |
Webhook events
GBP sends webhook events to your configured endpoint to notify your application of payment status changes, refunds, disputes and account updates. All webhooks are delivered as an HTTPS POST with a JSON payload and include a signature header for verification.
Event types
| Event | Description | When triggered |
|---|---|---|
payment.created | Payment initiated | Immediately after the create payment call |
payment.pending | Awaiting processing | Payment queued during high volume |
payment.requires_action | 3D Secure required | Customer must complete additional authentication |
payment.completed | Payment successful | Funds captured and confirmed by the acquiring bank |
payment.failed | Payment declined | Card declined, insufficient funds or fraud block |
payment.refunded | Refund processed | Full or partial refund completed |
payment.disputed | Chargeback filed | Customer initiated a chargeback with the issuing bank |
token.created | Card tokenized | New card token created |
transfer.completed | Payout sent | Withdrawal confirmed by the receiving bank |
account.updated | Account change | Merchant settings or limits modified |
Payload example — payment.completed
{
"id": "evt_7wX4yZv2bC6dE8fA",
"object": "event",
"type": "payment.completed",
"created_at": "2026-04-24T14:32:22Z",
"data": {
"object": {
"id": "pay_9xK2mNpQr5sT7uVw",
"status": "completed",
"amount": 25500000,
"currency": "USD",
"fee_amount": 38250,
"net_amount": 25461750,
"receipt_url": "https://portal.globalbusinessspay.com/receipts/pay_9xK2mNpQr5sT7uVw"
}
}
}Webhook signature verification
To confirm webhook payloads genuinely come from Global Business Pay and were not
tampered with in transit, every webhook includes a signature in the
X-GBP-Signature header. Verify it before processing the payload.
Verification steps
- Extract the timestamp from the
X-GBP-Timestampheader. Reject it if older than 5 minutes (replay protection). - Concatenate
timestamp + "." + raw_request_body. - Compute an HMAC-SHA256 using your webhook signing secret from the Merchant Dashboard.
- Compare with the
X-GBP-Signatureheader using a constant-time comparison.
const crypto = require('crypto');
function verifyWebhook(payload, signature, timestamp, secret) {
// Replay protection: reject webhooks older than 5 minutes
const now = Math.floor(Date.now() / 1000);
if (now - parseInt(timestamp, 10) > 300) {
throw new Error('Webhook timestamp too old — possible replay attack');
}
const signedPayload = timestamp + '.' + payload;
const expected = crypto
.createHmac('sha256', secret)
.update(signedPayload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}Error codes
GBP uses conventional HTTP response codes and returns detailed error objects so you can diagnose issues programmatically.
| Code | Status | Meaning |
|---|---|---|
200 | OK | Request succeeded |
201 | Created | Resource created successfully |
400 | Bad request | Invalid parameters or malformed JSON |
401 | Unauthorized | Invalid or missing API credentials |
403 | Forbidden | Insufficient permissions, or a sandbox key used on production |
404 | Not found | Requested resource does not exist |
409 | Conflict | Idempotency key reused with different parameters |
422 | Unprocessable | Card declined, validation failed or fraud block |
429 | Rate limited | Too many requests — retry after the specified delay |
500 | Server error | Internal error — contact support |
502 | Gateway error | Upstream processor unavailable — retry recommended |
503 | Maintenance | Scheduled maintenance — check the status page |
Error response format
{
"error": {
"code": "card_declined",
"message": "The card was declined by the issuing bank.",
"decline_code": "insufficient_funds",
"param": "source[number]",
"request_id": "req_8f3a2b7c1d4e5f6a",
"documentation_url": "https://docs.globalbusinessspay.com/errors/card_declined"
}
}Supported currencies
GBP supports 135+ currencies for payment processing and settlement. Multi-currency transactions convert at real-time mid-market rates with disclosed FX fees. You can hold balances in multiple currencies and withdraw to local bank accounts.
US Dollar
Euro
British Pound
Japanese Yen
Australian Dollar
Canadian Dollar
Swiss Franc
Chinese Yuan
South Korean Won
Indian Rupee
Turkish Lira
Israeli Shekel
Plus 120+ additional currencies. The full list is available via
GET /v2/currencies.
Country codes
GBP uses ISO 3166-1 alpha-2 country codes throughout the API. Country codes are required for billing addresses, bank account destinations, compliance screening and regional feature availability.
US — United States GB — United Kingdom DE — Germany
FR — France CA — Canada AU — Australia
JP — Japan SG — Singapore AE — UAE
IN — India BR — Brazil NG — Nigeria
ZA — South Africa HK — Hong Kong CH — Switzerland
SE — Sweden NL — Netherlands IE — IrelandRate limits
Requests are rate-limited per merchant account. Limits vary by endpoint type and
merchant tier. All rate-limited responses include a Retry-After header.
| Endpoint category | Starter | Growth | Enterprise |
|---|---|---|---|
| Read operations (GET) | 100/min | 500/min | 5,000/min |
| Write operations (POST/PUT) | 50/min | 300/min | 3,000/min |
| Tokenize card | 30/min | 200/min | 2,000/min |
| Webhook delivery | 60/min | 600/min | 10,000/min |
| Concurrent connections | 10 | 50 | 500 |
Rate limit headers
X-RateLimit-Limit— maximum requests allowed per window.X-RateLimit-Remaining— requests remaining in the current window.X-RateLimit-Reset— Unix timestamp when the limit resets.Retry-After— seconds to wait before retrying (on 429 only).
Terms & conditions
Merchant API agreement — legally binding
By integrating with, accessing or using the Global Business Pay Merchant API, you agree to be bound by these terms. This agreement is between your business entity and Global Business Pay Financial Services Ltd., a company registered in England & Wales (Company No. 08472910).
- API licence grant. GBP grants you a limited, non-exclusive, non-transferable, revocable licence to access and use the API solely for legitimate payment processing related to your business operations. You may not sublicense, resell or white-label API access without written consent.
- Acceptable use. You may not use the API for unlawful purposes, including money laundering, terrorist financing, sanctions evasion, unlicensed gambling or the sale of prohibited goods and services.
- Data security. You are responsible for securing API credentials on your systems. You must notify GBP within 4 hours of any suspected credential compromise.
- PCI-DSS obligations. If you collect card data directly you must maintain PCI-DSS Level 1 compliance and provide a quarterly Attestation of Compliance. Using GBP tokenization removes PCI scope from your environment.
- Service availability. GBP targets 99.99% monthly uptime. Scheduled maintenance is announced 72 hours in advance. Force majeure events are excluded.
- Intellectual property. All API documentation, SDKs, code examples and integration guides remain the property of Global Business Pay.
- Termination. Either party may terminate with 30 days written notice. GBP may suspend access immediately for security threats, regulatory requirements or material breach.
- Liability limitation. GBP's aggregate liability shall not exceed the total fees paid by the merchant in the 12 months preceding the claim. GBP is not liable for indirect, consequential or punitive damages.
- Governing law. These terms are governed by the laws of England & Wales. Disputes are resolved by binding arbitration under LCIA Rules, seated in London, in English.
- Amendments. GBP may update these terms with 30 days notice by email and dashboard notification.
Data protection & GDPR compliance
Global Business Pay is committed to data protection and privacy. As a data controller under GDPR and equivalent regulations, we implement technical and organisational measures to protect personal data processed through our API.
- Lawful basis. Processing is conducted under contract performance (Art. 6(1)(b) GDPR) and legal obligation (Art. 6(1)(c) GDPR) for financial compliance.
- Data minimisation. We collect only what is necessary for payment processing and regulatory compliance. Unused fields are purged after 90 days.
- Encryption. Data is encrypted at rest with AES-256 and in transit with TLS 1.3.
- Retention. Transaction data is retained for 7 years per AML regulations, then cryptographically shredded.
- Subject rights. You may exercise access, rectification, erasure, portability or objection rights by emailing support@globalbusinessspay.com with the subject line “GDPR Request”.
- Breach notification. Affected merchants and supervisory authorities are notified within 72 hours as required by GDPR Article 33.
- International transfers. Transfers outside the EEA use Standard Contractual Clauses with additional technical safeguards.
Liability, disputes & chargebacks
- Fraud liability. For fully authenticated 3D Secure transactions, liability shifts to the issuing bank. Non-3DS transactions carry merchant liability for fraudulent chargebacks.
- Chargeback process. When a cardholder disputes a transaction, GBP notifies the merchant by webhook within 24 hours. Merchants have 10 calendar days to submit evidence.
- Chargeback fee. Each chargeback incurs a $25 administrative fee. Excessive chargebacks above 1% of monthly volume may trigger an account review.
- Reserve requirements. GBP may hold a rolling reserve, typically 5–10% of monthly volume for 90 days, to mitigate chargeback risk.
- Pre-arbitration. If a chargeback is reversed and re-disputed, pre-arbitration fees of $250–500 may apply depending on the card network.
- Dispute resolution. Disputes first undergo 30 days of mandatory mediation, then binding arbitration under LCIA Rules in London.
- Indemnification. The merchant indemnifies GBP against claims arising from the merchant's products or services, fraudulent transactions originating from the merchant's systems, or breach of these terms.
Ready to integrate GBP payments?
Apply for a merchant account to receive API keys, sandbox access and integration support from our technical team.