card_id comes from, the four integration scenarios, statuses, fees, webhooks, sandbox testing and the go-live checklist.
pz_live_, pz_test_). They are separate from the Card Issuing API.Overview
Payins and payouts are part of one fiat product but are separate API operations:GET /transactions.
Core objects
Where card_id comes from
PointZero does not issue cards for fiat operations. The card already exists: it is the customer’s own bank card, and the customer enters its details in your interface.
Customer enters card details
Register the card
POST /cards.PointZero returns a card_id
card_id and returns it together with the masked card data (first6, last4, brand, currency, country, expiry).Store the card_id
card_id against your customer.Use it for payouts
card_id in every payout (and optionally in a payment) that should send funds to this card.external_customer_id, PointZero returns the existing card_id with 200 instead of 201.
active (can receive payouts), expired (expiry date has passed), inactive (deleted by you or disabled by PointZero).
Integration scenarios
- A. Payout to card
- B. Fiat to card
- C. Payin only
- D. Repeat payout
amount + fee is reserved on the balance immediately. If the payout fails or is cancelled, the reserved funds are returned.Payment methods
expires_in (300 to 604800 seconds). Available methods depend on your contract.
Edge cases
Environments and authentication
401. Requests to a resource that belongs to another organization return 404.
Requests and responses
Amounts
Amounts
"1000.00". Do not send amounts as numbers: floating point values lose precision.Currencies, countries and timestamps
Currencies, countries and timestamps
EUR, USD). Countries use ISO 3166-1 alpha-2 codes (ES, DE). Supported currencies, payment methods and countries depend on your contract and are returned by GET /limits.All timestamps are in UTC, ISO 8601 format: 2026-09-21T12:07:31Z.Your own references
Your own references
external_id, your own identifier for the operation (order ID, withdrawal ID). It is returned in responses and webhooks and can be used as a filter in list endpoints. external_id must be unique per operation type.metadata accepts up to 20 key-value pairs (keys up to 40 characters, values up to 500 characters). PointZero stores it and returns it without changes.Pagination
Pagination
limit (1 to 100, default 20) and starting_after (ID of the last item from the previous page).id of the last item in data as starting_after. Items are sorted by created_at, newest first.Idempotency
Idempotency
POST requests that create objects (/payments, /payouts, /cards) and cancel operations accept an Idempotency-Key header.- If a request with the same key and the same body is repeated, PointZero returns the original response and does not create a new object.
- If the same key is reused with a different body, PointZero returns
409 idempotency_key_reused. - Keys are stored for 24 hours.
- Use your own operation ID (order ID, withdrawal ID) or a UUID.
FX and fees
If the payout currency differs from the card currency, PointZero converts the funds at the rate applied when the payout is processed. The payout object shows the result:credited_amount = amount × exchange_rate, rounded to two decimal places. The card currency is returned in the card object (currency), so you can show the customer which currency the card will receive.
Fees are set in your contract and returned in each object.
Statuses
- Payment
- Payout
pending payments can be cancelled with POST /payments/{payment_id}/cancel. If funds arrive after cancellation, they are returned to the sender.succeeded as a completed operation. A successfully created payment or payout (201 response) means that the operation was accepted, not that money has moved.Service levels
compliance_review is not counted toward the payout SLA. Each payout includes expected_completion_at so you can show the customer when to expect the funds.
Balances and transactions
GET /balances returns the organization balance in each currency. This is the same balance shown in the dashboard and used for payouts.
GET /transactions returns the operation history. Filter by type, currency or source_id (the payment or payout ID). Amounts are positive for credits and negative for debits; net is the actual change of the balance.
Webhooks
PointZero sends a webhook every time a payment, payout or card changes status. Webhooks are the main way to learn about results. Polling should only be used for reconciliation.Setup
Add your endpoint URL in the dashboard under Settings → Webhooks, for examplehttps://client.com/api/pointzero/webhooks. The endpoint must use HTTPS. After saving, the dashboard shows the webhook signing secret (whsec_...). Sandbox and production have separate endpoints and secrets.
Delivery
- Respond with any
2xxstatus within 10 seconds. Process the event asynchronously if your handling takes longer. - Any other response or a timeout counts as a failed delivery. PointZero retries with increasing intervals for up to 24 hours.
- Events may arrive more than once and not always in order. Use the event
idto skip duplicates, and comparedata.statuswith what you already have stored instead of relying on arrival order. - Failed deliveries can be viewed and resent from the dashboard. All events for the last 30 days are also available through
GET /events.
Signature verification
The signature is an HMAC-SHA256 hex digest of the string{X-PointZero-Timestamp}.{raw request body}, using your webhook signing secret as the key.
- Read the raw request body before any JSON parsing.
- Build the signed string: timestamp, a dot, the raw body.
- Compute HMAC-SHA256 with your signing secret.
- Compare with
X-PointZero-Signatureusing a constant-time comparison. - Reject the request if the timestamp is more than 5 minutes old.
Event types
data field of every event contains the full object (payment, payout or card) in the same format as the API response.
Compliance
Depending on the jurisdiction, payment method and amount, PointZero may need additional information before an operation can be completed:- customer identification (name, date of birth, address, country);
- KYC or KYB data;
- source of funds information;
- sanctions and transaction screening results.
customer object in payments and payouts. external_customer_id is required; other fields help avoid compliance_review. Missing data does not block creation but can move an operation to compliance_review. While an operation is in review, the funds are held and no action from your side is needed unless the PointZero compliance team contacts you. The review ends with a *.succeeded, *.processing or *.failed event.
Limits and rate limiting
Limits depend on country, payment method, currency, operation type, customer and card. Read the current values withGET /limits and validate amounts in your interface before creating an operation. Pass card_id or external_customer_id to get the remaining amount for that card or customer today. If a limit is exceeded, the API returns 422 limit_exceeded and the error.param field names the limit.
Request limits are set per organization. Every response includes:
Errors
Errors have the same format on every endpoint. Includerequest_id when contacting PointZero support.
HTTP status codes
HTTP status codes
Error types
Error types
Error codes
Error codes
Failure codes
Failure codes
failed, the object contains failure_code and failure_message.Sandbox testing
The sandbox behaves like production but does not move real money. Usepz_test_ keys and the sandbox base URL. Each sandbox organization starts with a balance of 100,000.00 EUR and 100,000.00 USD. Successful sandbox payments add to it.
Test cards for payouts
Any future expiry date and any holder name can be used.Simulating payments
Bank transfers do not happen in the sandbox. Move a payment to the status you need withPOST /sandbox/payments/{payment_id}/simulate. Webhooks are sent as in production. To test underpayment or overpayment by bank transfer, pass received_amount together with status: succeeded.
processing, compliance_review, succeeded, failed (with an optional failure_code) and expired.
Go-live checklist
- Production API key created and stored on the server only
- Production webhook endpoint added, signing secret stored
- Webhook signature and timestamp verified
- Duplicate events skipped by event
id -
Idempotency-Keysent on everyPOST, retries reuse the same key -
card_idstored per customer, cards reused instead of re-registered - All payment and payout statuses handled, including
compliance_reviewandreversed -
received_amountandnet_amountused for bank transfers -
insufficient_balancehandled for payouts - Limits checked before creating operations
- Error handling with
request_idlogged - Reconciliation job using
GET /transactionsorGET /events - Customer data passed for compliance where required
- PCI DSS status confirmed with PointZero
- All scenarios tested in the sandbox
FAQ
Are payins and payouts separate products?
Are payins and payouts separate products?
POST /payments for payins and POST /payouts for payouts.Do we need different API keys for /payments and /payouts?
Do we need different API keys for /payments and /payouts?
Is there a separate dashboard for payouts?
Is there a separate dashboard for payouts?
Where does card_id come from? There is no endpoint to issue a card.
Where does card_id come from? There is no endpoint to issue a card.
POST /cards, and PointZero returns the card_id together with the masked card data. You store it and use it as the payout destination.The customer only sells and does not buy anything. What do we send?
The customer only sells and does not buy anything. What do we send?
POST /cards to get a card_id, then create a payout with POST /payouts. No payment is needed. The payout is completed within 15 minutes.Is card_id required when creating a payment?
Is card_id required when creating a payment?
Can we check the balance of the customer's card?
Can we check the balance of the customer's card?
How do we know that the money has arrived on the card?
How do we know that the money has arrived on the card?
payout.succeeded webhook, or status: succeeded in GET /payouts/{payout_id}.What happens to the money if a payout fails?
What happens to the money if a payout fails?
payout_refund transaction appears in GET /transactions.Versioning and changelog
The version is part of the URL (/v1). Within a version PointZero may add new endpoints, optional request fields, response fields, enum values and event types. Your integration should ignore unknown fields and handle unknown enum values gracefully. Breaking changes are released only in a new version, with advance notice.