We reply within 24 hours

Global Business Pay merchant API documentation

Integrate secure payment processing, card tokenization, cross-border transfers and merchant account management into your application.

API version 2.4.1 · Base URL 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

1
Your application Merchant website or mobile app initiates a payment request.
2
GBP API gateway Authenticated request validated, tokenized and encrypted.
3
Processing network Visa, Mastercard, SEPA, SWIFT or blockchain settlement.
4
Confirmation Real-time webhook plus API response with transaction details.

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

headers
Authorization: Basic <base64(api_key:secret_key)>
X-GBP-API-Version: 2024-01-15
X-GBP-Request-ID: req_8f3a2b7c1d4e5f6a
Content-Type: application/json

cURL example — authenticated request

bash
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.

EnvironmentBase URLPurpose
Sandboxhttps://api.globalbusinessspay.com/v2 Development, testing and integration validation. No real money moves.
Productionhttps://api.globalbusinessspay.com/v2 Live transactions with real funds. Requires verified merchant status.
Webhook testhttps://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.

POST/v2/payments

The payment status starts as pending and moves to completed, failed or requires_action for 3D Secure.

Request parameters

ParameterTypeDescription
amountRequiredinteger Payment amount in the smallest currency unit (cents). e.g. 5000 for $50.00.
currencyRequiredstring (3) ISO 4217 currency code, e.g. USD, EUR, GBP.
sourceRequiredobject Payment source: a card object, token ID or bank_transfer object.
descriptionOptionalstring (255) Human-readable description shown on customer statements.
customer_idOptionalstring Existing customer ID for repeat payments. Creates a new customer if omitted.
metadataOptionalobject Key-value pairs (max 20 keys, 500 characters each) attached to the transaction.
webhook_urlOptionalstring Override the default webhook URL for this transaction only.
idempotency_keyOptionalstring (100) Prevents duplicate charges. The same key with the same parameters returns the same response for 24 hours.
3d_secureOptionalboolean Force 3D Secure authentication. Default: true for EU cards.
captureOptionalboolean If false, creates an authorised hold only and you capture later. Default: true.

Request body — card payment

json
{
  "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)

json
{
  "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.

GET/v2/payments/:payment_id

Path parameters

ParameterTypeDescription
payment_idRequiredstring The payment ID returned from the create call. Format pay_xxxxxxxxxxxxxxxx.
bash
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.

POST/v2/payments/:payment_id/refunds

The sum of all refunds cannot exceed the original payment amount.

Request parameters

ParameterTypeDescription
amountOptionalinteger Refund amount in cents. If omitted, the full payment amount is refunded.
reasonOptionalstring One of requested_by_customer, duplicate, fraudulent, other.
metadataOptionalobject Additional key-value data attached to the refund record.
json
{
  "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.

GET/v2/payments?limit=50&status=completed&from=2026-04-01&to=2026-04-24

Default limit is 25 and the maximum is 100. Results are sorted by created_at descending.

Query parameters

ParameterTypeDescription
limitintegerResults per page. Default 25, max 100.
starting_afterstringCursor for pagination: pass the last object ID to get the next page.
statusstringFilter: pending, requires_action, completed, failed, refunded, disputed.
fromstring (date)Start date filter in YYYY-MM-DD format.
tostring (date)End date filter in YYYY-MM-DD format.
currencystringFilter by ISO currency code.
min_amountintegerOnly transactions with amount greater than or equal to this value, in cents.
max_amountintegerOnly 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.

POST/v2/tokens

The card number is validated with the Luhn algorithm and real-time BIN checking before tokenization.

json
{
  "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

json
{
  "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.

POST/v2/payments

Use a token ID as the payment source. The token must be valid and the associated card must not be expired or revoked.

json
{
  "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.

POST/v2/verify

Performs 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.

GET/v2/account
json
{
  "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.

GET/v2/balance
json
{
  "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"
}
All balance amounts are in the smallest currency unit (cents). Divide by 100 for display values. Available = Total − Pending − Reserved.

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.

POST/v2/transfers

Request parameters

ParameterTypeDescription
amountRequiredinteger Withdrawal amount in the smallest currency unit.
currencyRequiredstring (3) Currency code. Must match the available balance currency.
destinationRequiredobject Bank account object: account_number, routing_number or swift_bic, bank_name, country.
referenceOptionalstring Internal reference visible on the bank statement.
scheduleOptionalstring 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

EventDescriptionWhen triggered
payment.createdPayment initiatedImmediately after the create payment call
payment.pendingAwaiting processingPayment queued during high volume
payment.requires_action3D Secure requiredCustomer must complete additional authentication
payment.completedPayment successfulFunds captured and confirmed by the acquiring bank
payment.failedPayment declinedCard declined, insufficient funds or fraud block
payment.refundedRefund processedFull or partial refund completed
payment.disputedChargeback filedCustomer initiated a chargeback with the issuing bank
token.createdCard tokenizedNew card token created
transfer.completedPayout sentWithdrawal confirmed by the receiving bank
account.updatedAccount changeMerchant settings or limits modified

Payload example — payment.completed

json
{
  "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

  1. Extract the timestamp from the X-GBP-Timestamp header. Reject it if older than 5 minutes (replay protection).
  2. Concatenate timestamp + "." + raw_request_body.
  3. Compute an HMAC-SHA256 using your webhook signing secret from the Merchant Dashboard.
  4. Compare with the X-GBP-Signature header using a constant-time comparison.
javascript
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.

CodeStatusMeaning
200OKRequest succeeded
201CreatedResource created successfully
400Bad requestInvalid parameters or malformed JSON
401UnauthorizedInvalid or missing API credentials
403ForbiddenInsufficient permissions, or a sandbox key used on production
404Not foundRequested resource does not exist
409ConflictIdempotency key reused with different parameters
422UnprocessableCard declined, validation failed or fraud block
429Rate limitedToo many requests — retry after the specified delay
500Server errorInternal error — contact support
502Gateway errorUpstream processor unavailable — retry recommended
503MaintenanceScheduled maintenance — check the status page

Error response format

json
{
  "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.

USD

US Dollar

EUR

Euro

GBP

British Pound

JPY

Japanese Yen

AUD

Australian Dollar

CAD

Canadian Dollar

CHF

Swiss Franc

CNY

Chinese Yuan

KRW

South Korean Won

INR

Indian Rupee

TRY

Turkish Lira

ILS

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.

country codes
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 — Ireland

Rate 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 categoryStarterGrowthEnterprise
Read operations (GET)100/min500/min5,000/min
Write operations (POST/PUT)50/min300/min3,000/min
Tokenize card30/min200/min2,000/min
Webhook delivery60/min600/min10,000/min
Concurrent connections1050500

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.

BTC$96,420+1.84% ETH$3,284+0.92% USDT$1.00+0.01% BNB$712-0.64% SOL$188+2.31% XRP$2.42-1.12% ADA$0.92+0.45% DOGE$0.36-0.87% Sample rates · live feed loading