GBP Merchant API Documentation

Overview

The Global Business Pay Merchant API enables businesses and developers to integrate world-class payment processing capabilities directly into their applications, websites, and platforms. Built on RESTful principles with JSON data interchange, our API provides secure, scalable, and compliant payment infrastructure backed by over a decade of financial services expertise.

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 comprehensive toolkit you need with bank-grade security at every layer.

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 is performed via HTTP Basic Auth. Include your API Key as the username and Secret Key as the password in the Authorization header of every request. Requests without valid authentication will return a 401 Unauthorized error.

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 -X GET "https://api.globalbusinesspay.io/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. Secret Keys should only be used in server-to-server communication.
• Use environment variables to store API credentials. Never hardcode keys into your application source code.
• Rotate keys regularly — we recommend rotating Secret Keys every 90 days. Old keys remain valid for a 24-hour grace period.
• IP Whitelisting: Configure allowed IP addresses in your Merchant Dashboard to restrict API access to your servers only.

Base URLs & Environments

GBP provides separate environments for development/testing and production. All environments are globally distributed with automatic failover and maintain the same API contract.

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.

Request Parameters

{
  "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",
    "customer_tier": "premium_merchant"
  }
}

{
  "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.globalbusinesspay.io/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.

Path Parameters

curl -X GET "https://api.globalbusinesspay.io/v2/payments/pay_9xK2mNpQr5sT7uVw" \\
  -u "gbp_live_sk_abc123def456ghi789":"" \\
  -H "X-GBP-API-Version: 2024-01-15"

Process Refund

Refund a previously completed payment either partially or in full. Refunds are processed to the original payment source and typically settle within 5-10 business days for card payments, 1-2 days for bank transfers.

Request Parameters

{
  "amount": 500000,
  "reason": "requested_by_customer",
  "metadata": { "ticket_id": "SUPPORT-1024" }
}

List Transactions

Retrieve a paginated list of all transactions associated with your merchant account. Supports filtering by date range, status, amount, currency, and payment method.

Query Parameters

Tokenize Card

Securely store card details by converting them into a reusable token. Tokenized cards can be charged later without re-entering card details. GBP is PCI-DSS Level 1 certified — card data never touches your servers.

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

{
  "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. This enables one-click payments, subscription billing, and saved card workflows without storing sensitive card data on your servers.

{
  "amount": 50000,
  "currency": "USD",
  "source": "tok_3bN5pQr7sT9uVxYz",
  "description": "Monthly subscription - Premium Plan",
  "customer_id": "cus_7aB3cDe4fGh5iJk6"
}

Verify Card

Perform a zero-amount authorization to validate card details without charging the customer. This is useful for account verification, card validity checks before storing tokens, and KYC compliance workflows.

Merchant Account Info

Retrieve details about your merchant account including business profile, verification status, enabled features, API permissions, and compliance status.

{
  "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",
    "pci_compliance": "level_1",
    "sanctions_check": "cleared"
  },
  "created_at": "2020-03-15T09:22:00Z"
}

Check Balance

Retrieve real-time balance information for your merchant account across all supported currencies. Returns available balance, pending balance (funds in clearing), and reserved balance (held for disputes/chargebacks).

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

Note: All balance amounts are in the smallest currency unit (cents). Divide by 100 for display values. Available balance = Total - Pending - Reserved.

Withdraw Funds

Transfer available balance from your GBP merchant account 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.

Webhook Events

GBP sends webhook events to your configured endpoint URL to notify your application of real-time payment status changes, refunds, disputes, and account updates. All webhooks are delivered via HTTPS POST with a JSON payload and include a signature header for verification.

Event Types

{
  "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.globalbusinesspay.io/receipts/pay_9xK2mNpQr5sT7uVw"
    }
  }
}

Webhook Signature Verification

To ensure webhook payloads are genuinely from Global Business Pay and have not been tampered with in transit, every webhook includes a cryptographic signature in the X-GBP-Signature header. You must verify this signature before processing the payload.

Verification Steps

1. Extract the timestamp from X-GBP-Timestamp header. Reject if older than 5 minutes (replay attack protection).
2. Concatenate: timestamp + "." + raw_request_body
3. Compute HMAC-SHA256 using your webhook signing secret (found in Merchant Dashboard).
4. Compare with the X-GBP-Signature header using 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) > 300) {
    throw new Error('Webhook timestamp too old — possible replay attack');
  }
  // Build signed payload
  const signedPayload = timestamp + '.' + payload;
  // Compute expected signature
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');
  // Constant-time comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature), Buffer.from(expected)
  );
}

Error Codes

GBP uses conventional HTTP response codes and returns detailed error objects to help you diagnose issues programmatically. All error responses follow a consistent format with a human-readable message and machine-processable error code.

{
  "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.globalbusinesspay.io/errors/card_declined"
  }
}

Supported Currencies

GBP supports 135+ currencies for payment processing and settlement. Multi-currency transactions are automatically converted at real-time mid-market rates with transparent FX fee disclosure. 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

And 120+ additional currencies supported. Full list available via GET /v2/currencies endpoint.

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. All endpoints validate country codes against the official ISO standard.

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

To ensure platform stability and fair usage, API requests are rate-limited per merchant account. Limits vary by endpoint type and merchant tier. All rate limit responses include Retry-After header indicating seconds until the limit resets.

Terms & Conditions

Data Protection & GDPR Compliance

Global Business Pay is fully committed to data protection and privacy. As a Data Controller under GDPR and equivalent regulations worldwide, we implement technical and organizational measures to protect personal data processed through our API.

Liability, Disputes & Chargebacks

Understanding liability allocation and dispute resolution is essential for merchants integrating payment processing. This section outlines responsibilities, chargeback procedures, and dispute management workflows.