Global2Pay APIMerchant developer documentation

P2P payouts — the payer transfers straight into another user's bank account, with no house account in the normal path. This documentation lists every state your code has to handle.

Quickstart (15 minutes)

Overview

Full state machine

The sender's account is required up front

Omit both sender and sender_id and the call fails with 422 sender_required — no order is created. Money lands in a private bank account, so the system must be able to tell which slip belongs to which order. A transfer from a different account goes to a human review queue; it is not rejected.

Sender account rules

Successful slip intake answers 202

POST /v1/pay/deposits/{id}/slip has no immediate 409 duplicate_slip. It accepts with an order-scoped token and verifies later; the verdict arrives by webhook/status. Unconfirmed storage or queue admission returns a retryable 503 with the same key.

Why 202

One withdrawal, several deposits

A 10,000 withdrawal may be filled as 4,000 plus 6,000 by two different payers, so withdrawal.filled arrives more than once — not just at the end. Close the order only when status is settled and remaining_minor is 0.

Handling partial fills

Webhooks signed with a key pair, not a shared secret

We hold the private key; you hold the public key, fetched from GET /v1/webhooks/signing-keys with no authentication. A breach on our side still cannot forge a webhook. The Ed25519 signature covers the timestamp and the event id, which blocks replay and body swapping.

Verification code

Complete payloads, no read-back calls

Every event carries the full data.object as of that moment, with a version. Apply it with a single UPDATE guarded by WHERE version < new — no GET required. Delivery order is not guaranteed, and that version guard is what stops a stale event from overwriting fresher state.

The correct version guard

Minor units for money, UTC for time

Every money field is an integer in satang and ends in _minor (THB 5,000.00 is 500000). Every timestamp is RFC3339 UTC ending in Z with exactly three millisecond digits. Credit your end user with amount_received_minor; your merchant wallet moves by credited_amount_minor. They are different numbers.

Field dictionary

Where to start

What you are doing	Go to
First integration, want one deposit to run end to end	Quickstart
Signing requests (HMAC-SHA256) and getting 401	Request authentication
Working out which status means "credit the user"	Deposit statuses
Webhook signature verification fails	Verifying Ed25519 signatures
Withdrawal totals look wrong because events arrived out of order	Ordering and the version guard
Migrating from another gateway	Migrating from another provider
About to go to production	Go-live checklist

The three things that break most often

Only status = 'settled' means you may credit. slip_processing and under_review mean the money moved but the check is not finished. Do not release goods.
expired and canceled are not always final. If late_slip_accepted_until is present and is_terminal is false, the payer can still upload a slip after the fact. Do not fail the order yet.
202 is not an error. Slip upload returns accepted + receipt_id; the state transitions to slip_processing asynchronously later.