For merchants
Payin8 documentation
The merchant cabinet guide and the API reference: where to find each setting, where to put it and how requests work.
Setting up the merchant cabinet step by step.
Requests, responses, statuses and webhooks.
Cabinet
Quick start#
The merchant cabinet is where you get everything your server needs to work with the Payin8 API: the key and secret to sign requests, the webhook signing secret, and the payment page settings. Here you also see deals, the balance and disputes, and manage your team.
Menu items, tabs and buttons below are named as they appear in the English version of the cabinet. The menu items you see depend on the rights of your role (see Team and roles).
From invitation to the first deal#
- Accept the invitation. Payin8 invites the first member of your organization (the owner). Open the invitation link, set a password and sign in. Details: Sign-in and account.
- Turn on two-factor authentication (2FA). It is mandatory for the owner: until it is set up, the cabinet is not available. Save the recovery codes — they are shown once.
- Check the project. Payin8 creates projects for you. Open Connection → Projects, select the project and look at the "Methods and limits" tab: which directions are on (pay-in, payout), what the amount limits are, and what the tariff is. If no tariff is set for a direction, deals in that direction are not created. See Organization and projects.
- Issue an API key. Connection → API keys → "Issue a key": select the project, enter a name, rights and the IP addresses of your server. Save the key ID and the secret — the secret is shown once. See API keys.
- Set up the webhook. Connection → Projects → project → "Webhook" tab → "Set up": enter the address and the events. After the first save, the cabinet shows the signing secret once. Click "Send a check" to send a test event. See Webhooks.
- Design the payment page. The "Payment page" tab of the project (or Organization → Profile and rules for all projects at once): shop name, logo, colour, support contacts, return addresses to your site. See Payment page.
- Check the rules. The "Rules" tab of the project: "Language of the payment page", "Client receipt required", "Late confirmation of pay-ins", "Payout without funds on the balance". See Rules.
- Create the first deal. Your server sends a signed request to create a pay-in — see Pay-ins and Request signing. The deal appears in Pay-ins, and the webhook event in Connection → Webhook delivery.
- For payouts you need a balance (it grows with pay-in credits or with a USDT transfer, Money → Top-up) and a key with the "Create payouts" right and a non-empty list of IP addresses. See Payouts.
- Invite your team: Organization → Team → "Invite". See Team and roles.
Warning
After some security changes (sign-in with a recovery code, password reset by link, setting up 2FA again) the cabinet temporarily blocks issuing keys, changing the webhook, adding withdrawal addresses and withdrawals. By default, for 24 hours. Details: Security.
What you need to connect and where to get it#
| What you need | Where to get it in the cabinet | Where to put it on your side |
|---|---|---|
| API address | — | Base address of your server's requests: https://api.payin8.io (see API overview) |
| Key ID | Connection → API keys → "Issue a key", "The secret of the key" window, "Key" field. Later — in the key card, "Key" field | The X-Api-Key header of every request |
| Key secret | The same window, "Secret" field. Shown once | Your server's secret store; it signs every request (X-Signature header, see Request signing) |
| Headers and string to sign | The same window, "Headers of a request" and "String to sign (six lines)" blocks — a sample | Your request signing code; details — Request signing |
| IP addresses of your server | You set them yourself: the "Addresses" field in the "New key" or "Change the key" window | If the list is not empty, Payin8 accepts requests with this key only from these addresses |
| Webhook address | You set it yourself: Connection → Projects → project → "Webhook" → "Set up", "Address" field | A handler on your server that accepts POST requests from Payin8 |
| Webhook signing secret | The "Signing secret" window after the first webhook save or after "Replace the secret". Shown once | Signature check of incoming webhooks (see Webhooks) |
| Webhook events | The same place, "Events" block | Your webhook handler: which event types to expect |
| Project ID | Connection → Projects → project → "Overview", "Project ID" field | For reconciliation and support requests; the key is already bound to the project |
| Deal amount limits and tariff | Connection → Projects → project → "Methods and limits" | Checking the order amount before creating a deal; your server can also get the available methods through the API (see API overview) |
| Return addresses to your site | Connection → Projects → project → "Payment page" → "Edit", "Return to your site" block | Pages of your site after a successful and a failed payment; an address sent with the pay-in through the API takes precedence (see Pay-ins) |
| Name, logo, colour, support on the payment page | The same place | — |
| Payment link for the client | Pay-in card, "Payment link" block | You can send it to the client if they lost the page |
| Payment page domain | Not configured in the cabinet | Contact Payin8 support (see Payment page) |
| Withdrawal address (USDT, TRON network) | Money → Wallets → "Add an address" | Your wallet; you can withdraw to a new address after a pause — by default 24 hours after it is added |
| Top-up address (USDT, TRON network) | Money → Top-up | A USDT transfer from your wallet to top up the balance |
Cabinet
Sign-in and account#
Invitation#
You can get into the cabinet only by invitation. Payin8 invites the owner of the organization. Other members are invited by the owner or by a team member with the right to invite (see Team and roles).
- Open the invitation link. The "Invitation" page shows the role you will get and how long the link is valid ("Valid until").
- Enter your name ("Your name (optional)"), then "New password" and "Repeat the password".
- Click "Set password", then sign in with your e-mail and the new password.
Password requirements (the cabinet shows them under the field):
- 12 to 128 characters (Payin8 can raise the lower limit);
- the password does not contain the part of your e-mail before
@if that part has 4 or more characters (case-insensitive); - both fields match.
By default, an invitation link is valid for 72 hours (Payin8 sets the term). Each new link cancels the previous one. If the link has expired, ask the cabinet owner (or Payin8, if Payin8 sent the invitation) to send the invitation again.
Note
An invitation link opens only in the cabinet it was issued for. If you opened it in the wrong place, the page tells you where to open it.
Sign-in#
- On the "Sign in" page, enter "E-mail" and "Password" and click "Sign in".
- If you have 2FA turned on, enter the 6-digit code from your authenticator app. If your phone is not at hand, click "No access to the app — use a recovery code".
You have 5 minutes to enter the code after the password; after that, start the sign-in again.
After several failed attempts in a row, sign-in for the account is temporarily blocked: by default, after 5 wrong passwords within 15 minutes — for 15 minutes (Payin8 sets the numbers).
Forgot your password? There is no self-service recovery. Ask the cabinet owner to issue a new password link (Organization → Team → member → "Password link") or contact Payin8 support. The link works once and is valid for 30 minutes by default. After a password change by link, all sessions end, 2FA stays, and sensitive actions are blocked for a while (see Security).
Two-factor authentication#
Two-factor authentication (2FA) uses one-time codes from an authenticator app (Google Authenticator, 1Password and others).
- For the owner role and for roles with rights that need a fresh code, 2FA is mandatory: without it the cabinet is not available, and on the first sign-in the "Protect your sign-in" screen opens.
- For other roles it is optional, but without it withdrawals, API keys and team management are not available.
To turn it on:
- If the cabinet did not offer the setup itself, open the "Account" menu (the icon in the top right corner) → "Profile and security", the "Second factor" block, and click "Turn on".
- Enter the "Current password" and click "Start".
- Scan the QR code with the app or enter the "Secret" manually. Enter the "Code from the app" and click "Verify". You have 10 minutes for the setup.
- Save the recovery codes and click "I saved the codes".
If the code does not work, check that the time on your phone is set automatically.
Moving to a new phone. "Profile and security" → "Move to another phone": confirm with a code from the old device and scan the new QR code. The move issues new recovery codes and ends your sessions on other devices.
You can turn off 2FA only if your role does not require it ("Turn off", with the current password and a code).
Phone lost and no codes. Ask the cabinet owner to reset your 2FA (Organization → Team → member → "Reset second factor"). If you are the owner, contact Payin8 support. After the reset, you set up 2FA again at the next sign-in.
Recovery codes#
When you turn on 2FA, the cabinet gives you 10 recovery codes. They are shown once: click "Copy all" or "Download .txt" and keep them where you keep your passwords.
- Each code works once.
- Signing in with a recovery code blocks sensitive actions for a while (see Security).
- When few codes are left, the cabinet warns you. To get a new set: "Profile and security" → "New recovery codes" (you need a code from the app). The previous codes stop working.
Confirming actions with a code#
The cabinet confirms sensitive actions with a fresh code from the app ("Confirm the action" window): issuing and changing an API key, replacing a secret, setting up the webhook, changing a project and the payment page, adding a withdrawal address and withdrawing, managing the team and roles.
- One code confirms one action. If the code is already used, wait for the next one — the cabinet shows in how many seconds it appears.
- After several failed code attempts (by default 5 within 15 minutes) all your sessions end — sign in again.
Revoking an API key and resending a webhook do not need a code: protective actions must be fast.
Password#
"Profile and security" → "Password" block: enter the "Current password", the new password twice, and click "Change password". Your sessions on other devices end; the current one stays. The new password must differ from the previous one.
Sessions#
The "Sessions" block in "Profile and security" shows where you are signed in now: when the session started, the last activity and the sign-in method ("password only", "with a code", "with a recovery code").
- "End" closes one session.
- "Sign out on other devices" closes all sessions except the current one.
- In the "Account" menu: "Sign out" — from this browser, "Sign out everywhere" — on all devices.
A session ends by itself after 24 hours without activity and no later than 7 days after sign-in (Payin8 sets the terms). The exact time is shown in the "Session ends at the latest" field.
Language, theme and time zone#
- Language — the language menu in the cabinet header: English, Español, Русский.
- Theme — the "Theme" menu in the header: "Light", "Dark", "System".
- Time zone — "Profile and security" → "Display" block → "Time zone". By default, the browser time zone.
Language and theme are also in the "Display" block. These settings are stored only in the current browser.
To move around the cabinet quickly, use the search in the header ("Search…"): a section, a deal number or an ID.
Cabinet
Organization and projects#
Organization#
Organization → Profile and rules shows the data of your organization in Payin8:
- "Contacts" — "E-mail" and "Telegram" that Payin8 uses to contact you about your account. Clients do not see them. To change them, click "Change" (you need the "Change contacts" right); an empty field removes the contact.
- "Organization", "Status" and "With the platform since".
- The "Lead" block — if a Payin8 partner brought you: who the partner is, since when, what they see and which of your settings they can change. The lead sees your deals without client data and payment details; each of their changes goes to the "Activity log".
- "Default rules" — rule values for all projects (see below).
- "Default payment page" — the payment page design for all projects (see Payment page).
What a project is#
A project is a source of your pay-ins and payouts: for example, a separate website or app. Each project has its own payment methods, amount limits, tariff, rules, API keys, webhook and payment page. An API key belongs to one project, so deals created with this key belong to that project.
Payin8 creates projects and sets their methods, limits and tariffs. If you need one more project or other limits, contact Payin8 support.
Project list#
Connection → Projects is a table: "Name", "Status", "Methods" (pay-in, payout), "Created". You can filter by status. Click a project to open its card.
Project statuses:
| Status | Meaning |
|---|---|
| "Active" | The project accepts new deals |
| "switched off by you" | You switched the project off; new pay-ins and payouts are rejected, deals in progress run to the end |
| "switched off by the platform" | Payin8 switched the project off; only Payin8 can switch it on |
Project card#
Card tabs (each is visible if your role has the right for it):
| Tab | What is there |
|---|---|
| "Overview" | "Project ID", status, reason and time of the last status change, creation date |
| "Methods and limits" | For each method and currency: whether pay-in and payout are on, and the amount limits; the "Tariff" block |
| "Rules" | Project rules (see below) |
| "API keys" | A short list of the project keys and the "All keys of the project" link |
| "Webhook" | The address, events and signing secrets of the project webhook (see Webhooks) |
| "Payment page" | The project payment page design and return addresses (see Payment page) |
Actions in the card header (each is confirmed with a code from the app):
- "Rename" — a new name, 1 to 60 characters.
- "Switch off" — you can give a reason (3–500 characters, optional). New pay-ins and payouts of the project are rejected; deals in progress run to the end.
- "Switch on" — the project accepts new deals again. You cannot switch on a project that Payin8 switched off.
Methods, limits and tariff#
The "Methods and limits" tab shows what is set up for the project:
- the method (for example, "Bank transfer") and the currency;
- "pay-in" and "payout" — the smallest and the largest amount of one deal, or "off";
- the "Tariff" block — for each direction that is on: the fee rate (a percentage, plus a minimum and a fixed part if they are set) and where it comes from: "set for this project" or "set for the whole organization".
If no tariff is set for a direction that is on, the cabinet shows the warning "Tariff not set: deals in this direction are not created." Payin8 changes limits and tariffs.
The fee of each deal is shown in its card (see Deals). Your server can also get the available methods through the API — see API overview.
Rules#
Rules are settings for how deals work. You see them on the "Rules" tab of a project and in the "Default rules" block on the "Profile and rules" page. Next to each value, the cabinet shows where it comes from: "platform default", "platform default for the currency", "set for the organization" or "set for the project".
How inheritance works: a project value takes precedence over an organization value, and an organization value takes precedence over the platform default. The "Change" button sets your own value (the "Change the rule" window). The "Inherit" button removes your value, and the value from the level above applies again (you need the "Reset rules" right).
Rules you can change yourself (you need the "Change rules" right):
| Rule | Values | Default |
|---|---|---|
| "Late confirmation of pay-ins" | "on" / "off". If off, a pay-in with an expired payment term is not confirmed later | on |
| "Payout without funds on the balance" | "reject at once" / "wait for a top-up" (the payout waits for a balance top-up until the end of its term) | reject at once |
| "Client receipt required" | "on" / "off". If on, the client attaches the transfer receipt on the payment page before reporting the payment | off |
| "Language of the payment page" | "as the pay-in" / "Spanish" / "English" | as the pay-in |
Rules set by Payin8 (marked "set by the platform" in the cabinet):
| Rule | Default |
|---|---|
| "Payment term of a pay-in" — how much time the client has to pay after the payment details are issued | 15 min |
| "Late confirmation window after the payment term" | 24 h |
| "How long a payout waits to be taken" — from payout creation, including the wait for funds on the balance | 4 h |
| "Time to open a dispute on a deal" — from deal creation | 7 days |
Payin8 can change the default values and set its own values for your organization or project. The cabinet always shows the value in effect.
Cabinet
API keys#
An API key is what your server uses to sign requests to the Payin8 API. A key has two parts:
- key ID — sent in the open in the
X-Api-Keyheader; - secret — kept only by you; it is used to compute the
X-Signaturesignature. The secret itself is never sent in requests.
How the headers and the signature work: Request signing.
Where the keys are#
Connection → API keys lists all keys of your projects. Columns: "Name", "Project", "Status", "Rights" (a count), "Addresses", "Last used", "Secret" (last 4 characters), "Issued". You can filter by project and status.
The keys of one project are also visible in the project card, "API keys" tab.
Key statuses: "active", "revokes" (the key was replaced and stops working at the shown time), "revoked".
Issuing a key#
- Connection → API keys → "Issue a key".
- Fill in the "New key" window:
- "Name" — 1 to 60 characters, to tell keys apart;
- "Project" — a key belongs to one project;
- "Rights" — what the key is allowed to do (see below);
- "Addresses" — the IP addresses of your server, one per line (see below).
- Confirm with a code from the app.
- "The secret of the key" window opens with the "Key" (ID) and "Secret" fields, and the "Headers of a request" and "String to sign (six lines)" samples. Copy the key and the secret to your server's secret store and click "I saved the secret".
Warning
The secret is shown once. Payin8 cannot show it again. If the secret is lost, replace it ("Replace the secret") or issue a new key.
How many keys. By default, a project can have at most 2 active keys (Payin8 can change this number). A key that was replaced but still works also counts.
Key rights#
By default, a key gets all payment API rights that you can grant. The issue window shows what the key will get; clear what is not needed. At least one right must stay.
| Right in the cabinet | What it allows |
|---|---|
| "Create pay-ins", "Read pay-ins", "Cancel pay-ins" | Working with pay-ins — see Pay-ins |
| "Create payouts", "Read payouts and their receipts", "Cancel payouts" | Working with payouts — see Payouts |
| "Read the balance" | The balance — see Balance |
| "Open disputes", "Read disputes" | Disputes — see Disputes |
| "Read the payment methods" | Payment methods of the project |
| "Upload files" | Receipts and other files — see Files |
The "Create payouts" and "Cancel payouts" rights are marked as money rights. Only the owner or a team member with the "Give money rights to API keys" right can grant them to a key. Others see these rights as unavailable. Changing the rights and addresses of a key that already has money rights, and replacing its secret, is also allowed only to someone who can grant these rights.
IP address list#
In the "Addresses" field, enter the IP addresses your servers call the API from: one per line, CIDR ranges allowed, up to 20 lines.
- If the list is empty, the key works from any address ("any address").
- To create payouts, and pay-ins that return payment details right in the response, the key needs a non-empty IP list. Without it, such a request is rejected with
ip_allowlist_required(see Errors). Payin8 decides which operations require the list. - A range cannot be wider than
/24for IPv4 and/56for IPv6.
We recommend restricting the addresses of every key.
Changing a key#
Key card (click a key in the list) → "Change": name, addresses and rights. The change is confirmed with a code from the app and applies at once; the ID and the secret do not change.
The card also shows: "Key" (ID), "Project", the last characters of the secret, "Last used", "Issued by", "Issued", the list of addresses and rights.
Replacing the secret#
Key card → "Replace the secret". In the "The old secret works" field, choose how long the old key keeps working: "stops at once", "one more hour", "one more day" (selected by default), "seven more days". Confirm with a code from the app.
The cabinet shows "The secret of the key" window with a new key ID and a new secret — replace both values on your server. The name, rights and addresses move to the new key. The old key gets the "revokes" status and stops working at the chosen time.
Tip
While the old key works, it takes a place in the project's limit of active keys. If the project already has 2 active keys, a replacement with overlap fails: choose "stops at once" or revoke an extra key first.
Revoking a key#
- Key card → "Revoke". You can leave a "Note". Requests with this key stop passing at once. A revocation cannot be undone.
- Connection → API keys → "Revoke all": select the project and type the word "REVOKE". All active keys of the project stop working at once.
Revoking does not need a code from the app, so that you can do it fast, for example if a secret leaks.
Who can do this#
| Action | Role right |
|---|---|
| See keys | "See API keys" |
| "Issue a key" | "Issue API keys" |
| "Change" | "Change API keys" |
| "Replace the secret" | "Replace the secret of a key" |
| "Revoke" | "Revoke API keys" |
| "Revoke all" | "Revoke all API keys at once" |
| Grant money rights | The owner or "Give money rights to API keys" |
The system roles "Operator" and "Viewer" have no access to keys. Issuing, changing and replacing the secret require 2FA to be on and are blocked for a while after security changes (see Security).
Cabinet
Webhooks#
A webhook is a POST request with JSON that Payin8 sends to your server's address when a deal or a dispute changes. Each project has one webhook address. Each request is signed with the signing secret. Body format, headers and signature check: Webhooks.
Where to set the address#
- Connection → Projects → project → "Webhook" tab.
- Click "Set up" (if no address is set yet) or "Change".
- Fill in the form:
- "Address" — the handler address on your server;
- "Events" — which events to subscribe to (see below); at least one;
- "Send events" — a switch. A switched-off address keeps its settings, but deliveries waiting in the queue are canceled.
- Click "Save" and confirm with a code from the app.
Address requirements (the cabinet checks them at once):
https://only;- a host name with a domain, not an IP address;
- no user name or password in the address, and no part after
#; - at most 2048 characters;
- port
443or8443(Payin8 sets the list of allowed ports); - the address must not lead to an internal network; addresses of some domains are not allowed.
If you change the address, deliveries that are still being retried go to the new address.
Where to get the signing secret#
On the first webhook save, Payin8 creates a signing secret and shows it once in the "Signing secret" window. Save it to your server's secret store and click "I saved the secret".
Warning
Payin8 does not keep the signing secret in readable form. If you lost it, replace the secret.
Replacing the secret. "Webhook" tab → "Replace the secret" → confirm with a code from the app. The new secret is shown once. For some time (24 hours by default, Payin8 sets the term) the previous secret signs requests together with the new one: during this time the signature header has two v1 values. This gives you time to switch your server to the new secret without losing events. The "Signing secrets" block shows which secret is "current", which is "retiring", and until when it signs.
A short note on checking the signature is on the tab, in the "How to check the signature" block; the full description is in Webhooks.
Events#
| Event in the cabinet | Type | When it comes |
|---|---|---|
| "Pay-in: account issued" | payin.assigned |
Payment details are assigned to the pay-in |
| "Pay-in credited" | payin.completed |
The pay-in is completed, the money is credited to the balance |
| "Pay-in failed" | payin.failed |
The pay-in is closed without payment |
| "Pay-in amount changed" | payin.amount_changed |
The client paid a different amount, the pay-in amount is changed |
| "Payout executed" | payout.completed |
The payout is executed |
| "Payout failed" | payout.failed |
The payout is closed without execution |
| "Dispute opened" | dispute.opened |
A dispute is opened on a deal |
| "Dispute closed" | dispute.closed |
The dispute is closed |
| "Check" | webhook.ping |
You clicked "Send a check" |
On the first setup, all events are selected. The content of each event: Webhooks and Statuses.
Test event. The "Send a check" button on the "Webhook" tab sends the "Check" event to the current address. After it is sent, you can go straight to it: "Open in the log".
Delivery log#
Connection → Webhook delivery shows each event of your projects, its deliveries and attempts.
- Columns: "Created", "Event", "Project", "Deal", "Delivery" (status), "Attempts", "Last answer", "Next attempt".
- Filters: "Project", "Event", "Delivery" and a period of at most 31 days.
- Event card: "Body as sent" and all deliveries with attempts — time, duration, address, response code or error.
Delivery statuses:
| Status | Meaning |
|---|---|
| "Queued" | The delivery is still in progress: an attempt is scheduled |
| "Delivered" | Your server answered with a 2xx code |
| "Failed" | The retry window ended without a successful answer |
| "Canceled" | The delivery was canceled: for example, the address was switched off while the delivery waited in the queue |
If an event has no deliveries, then at the moment of the event the address was not set, was switched off, or was not subscribed to this event type. Such events stay in the log, but they are not sent automatically after the address is set up — you can send them manually (see below).
All events of one deal are also visible from its card: "Webhooks" tab → "Open the deliveries of this deal".
On the project's "Webhook" tab, the "Delivery" block shows how the address responds: whether the last delivery succeeded, how many failed attempts in a row, "Last answer" and "Last attempt".
Events and deliveries are kept for 90 days, the attempt log for 30 days (Payin8 sets the terms).
Retries and resending#
A delivery succeeds when your server answers with a 2xx code. Answer fast: by default, Payin8 waits at most 5 seconds for the connection and at most 10 seconds for the whole request. Otherwise Payin8 retries with a growing pause: the first pause is about 10 seconds, then each one is twice as long, but at most 6 hours. Retries continue for 24 hours after the event; the last attempt is at the very end of this window. After that, the delivery gets the "Failed" status. Payin8 sets the schedule.
Send again. The event card in the log has a "Send again" button. If the delivery is still queued, the attempt runs at once; otherwise a new delivery of the same body to the current project address is created, with a new 24-hour retry window. You can send again while the event is kept, and only if the webhook address is switched on. There is no bulk resend in the cabinet.
What happens during long outages#
- Payin8 does not switch off the address automatically because of failed deliveries: each new event is delivered with its own retry window.
- If your server did not answer for longer than the retry window, the deliveries get the "Failed" status. After recovery, send the events you need manually ("Send again") or reconcile the deal states through the API (see Pay-ins, Payouts).
- Payin8 can switch off the webhook itself. Then the tab shows "switched off by the platform": events are kept but not sent, and only Payin8 can switch the address on again — contact Payin8 support.
Who can do this#
| Action | Role right |
|---|---|
| See the "Webhook" tab and the delivery log | "See webhooks" |
| "Set up", "Change", "Replace the secret" | "Change webhook settings" (with a code from the app) |
| "Send a check", "Send again" | "Resend webhook events" |
The system role "Operator" can send events again but cannot change settings. Changing the webhook settings is blocked for a while after security changes (see Security).
Cabinet
Balance and top-ups#
Overview#
Overview is the first page of the cabinet: the balance and deal counters right now — how many pay-ins are awaiting payment or have the client's payment report, how many payouts are created, looking for an executor or being executed, how many deals created in the last 24 hours are already completed or expired, and how many withdrawal requests await approval. Click a counter to open the filtered list. Below are the "Latest deals".
Balance#
Money → Balance and statement shows the organization's money by currency. For each currency:
| Field | Meaning |
|---|---|
| "Available" | Money you can spend on payouts and withdraw |
| "Frozen" | Money held for payouts in progress and withdrawal requests |
| "Total" | Available plus frozen |
Frozen money returns to "Available" if a payout is canceled or a withdrawal request is rejected. Under the cards, there is an estimate "In USDT at the withdrawal rate" — about how many USDT you would get if you withdrew the whole balance.
How money moves:
- Pay-in. When a pay-in is completed, the amount the client paid, minus the tariff fee, is credited to "Available".
- Payout. When a payout is created, the amount to be debited from the balance is frozen. When the payout is executed, the frozen amount is debited; on partial execution, the remainder returns to "Available". If there is not enough money, the payout is rejected at once or waits for a top-up — this is set by the "Payout without funds on the balance" rule (see Rules).
- Withdrawal. A withdrawal request freezes pesos until Payin8 decides on it (see Wallets and withdrawals).
- Top-up. A USDT transfer is credited in pesos (see below).
You can also get the balance through the API — see Balance.
Statement#
Under the cards is the "Statement": every money movement in one currency.
- Filters: "Currency", "Operations" ("All operations", "Pay-ins", "Payouts", "Withdrawals", "Top-ups", "Adjustments"), "Bucket" ("Available", "Frozen", "Both") and a period of up to 366 days.
- Columns: "Time", "Operation", "Document" (deal, withdrawal, top-up or adjustment — with a link), "Part" (available or frozen), "Change", "Balance after".
- "Totals of the period" — "At the start", "At the end", "In", "Out" and the "By operation" breakdown. Totals are computed for periods of up to 92 days.
Main statement operations:
| Operation | What happened |
|---|---|
| "Pay-in credited" | The pay-in is completed, the money minus the fee is credited |
| "Pay-in credited (paid after the deadline)" | The same, but the payment was confirmed after the term |
| "Pay-in credit canceled by a dispute" | The pay-in credit is canceled by a dispute decision |
| "Frozen for a payout" | The payout amount is frozen |
| "Unfrozen: the payout was canceled" | The payout is canceled, the money returned to "Available" |
| "Payout executed (a partial remainder returns to the balance)" | The payout is executed, the frozen amount is debited |
| "Payout returned by a dispute" | The payout is returned by a dispute decision |
| "Withdrawal: frozen" / "Withdrawal: unfrozen" / "Withdrawal: done" | Movements of a withdrawal request |
| "USDT top-up" | A top-up is credited |
| "Credit by the platform" / "Debit by the platform" | A manual adjustment by Payin8 |
Top-up#
You can top up the balance with a USDT transfer — for example, to have enough money for payouts.
- Open Money → Top-up. It shows the Payin8 address on the TRON network (with a QR code), the "Minimum" and the "Top-up price now".
- Transfer USDT (TRC-20) to this address from your wallet.
- After the required number of network confirmations, Payin8 credits pesos at the top-up price at the moment of crediting. The credit appears in the "Top-ups" history and in the statement as "USDT top-up".
Warning
Transfers below the minimum are not credited. The default minimum is 10 USDT; the current value is shown on the page. Transfer only USDT on the TRON network.
Payin8 registers the transfer by its transaction hash; until then it is not in the history. If a transfer does not appear for a long time, send the transaction hash to Payin8 support.
The "Top-ups" history: "№", "Registered", "Transfer" (the hash with an "Open in the explorer" link), "Amount", "Status", "Price", "Credited", "Credited at". Statuses: "Registered", "Credited", "Rejected", "Refunded".
If the page says "Top-up is not set up", top-ups are not available to you now — contact Payin8 support.
Who can do this#
| What | Role right |
|---|---|
| "Balance and statement" | "See the balance and statement" |
| USDT estimate, prices | "See exchange rates" |
| The "Top-up" page | "See the top-up address" |
| Top-up history | "See top-ups" |
Cabinet
Wallets and withdrawals#
A withdrawal exchanges pesos from your balance for USDT at the Payin8 rate and sends them to your address on the TRON network. First add an address, then create a request; Payin8 approves the request.
Withdrawal addresses#
Money → Wallets lists the USDT addresses on the TRON network (TRC-20) that withdrawals go to.
To add an address:
- Click "Add an address".
- "Address" — paste it from your wallet. A TRON address starts with
Tand has 34 characters; Payin8 checks the checksum. - "Label" — 1 to 64 characters: how the address is named in the cabinet.
- Confirm with a code from the app.
Warning
Check the address: a transfer to a wrong address cannot be returned. Adding and removing an address are recorded in the "Activity log".
When you can use an address. A new address becomes available for withdrawals 24 hours after it is added (Payin8 sets this pause). Until then its state is "Not yet usable", and the "Usable from" field shows the time. After that — "Usable".
Other states: "Blocked by the platform" — the address does not accept withdrawals, you can only remove it; "Removed" — removed addresses are hidden, you can show them with the "Show removed" button.
Actions with an address (with a code from the app): "Rename" and "Remove". Requests already created to a removed address will not be approved.
You can have at most 10 addresses, not counting removed ones (by default; Payin8 sets the number).
Creating a withdrawal#
Money → Withdrawals → "New withdrawal". A three-step wizard.
1. "How much". The "What you can withdraw" block shows: "Available", "Largest amount to exchange", "Minimum", "Maximum per request", "Left for today", "Withdrawal fee", "Exchange fee" and "Approximate price". Enter the amount in one of two ways:
- "In pesos" — "How many pesos to exchange";
- "In USDT" — "How many USDT to receive".
The "Everything available" button fills in the whole available balance. Click "Next".
2. "Where to". Select an address from the list. You cannot select an address that is not usable yet. You can also add a new address here, but you can withdraw to it only after the pause.
3. "Calculation and confirmation". Click "Calculate". The cabinet shows: "You exchange", "Debited from the balance", "You get", "To", "Final price with fees". The price is fixed for a short time (2 minutes by default; "The price is fixed for" timer). If the time is up, click "Recalculate". If you want, add a "Comment" (up to 500 characters; Payin8 sees it) and click "Create the request" — with a code from the app.
Limits and fees are set by Payin8; the values in effect are always shown in the "What you can withdraw" block. Defaults for merchants: the minimum is 50 USDT per request, the withdrawal fee is 1% of the exchanged peso amount on top of it, the exchange fee is 0%; by default there is no "Maximum per request" and no 24-hour limit ("Left for today").
If withdrawals are switched off, the wizard shows "Withdrawals are switched off by the platform" — contact Payin8 support.
Requests and statuses#
Money → Withdrawals is the request list: "№", "Created", "Status", "Debited", "You get", "Address", "Price". You can filter by status and period.
| Status | What is happening |
|---|---|
| "Awaiting approval" | Pesos are frozen on the balance until Payin8 decides |
| "Approved" | USDT will be sent to your address |
| "Confirming" | The transfer is in the network, waiting for confirmations |
| "Completed" | USDT arrived at your address |
| "Send failed" | Payin8 is investigating; pesos stay frozen |
| "Canceled" | You canceled the request; pesos returned to the balance |
| "Rejected" | Payin8 rejected the request (the reason is in the card); pesos returned to the balance |
| "Returned to balance" | Payin8 returned the pesos to the balance; USDT were not sent |
The request card has the "Amounts", "Price" and "Transfer" blocks ("Address", "Transfer hash" with the "Open in the explorer" link).
While a request awaits approval, you can:
- "Cancel the request" — pesos return to the balance; a canceled request cannot be restored;
- "Update the price" — the request is recalculated at the current price: the debited pesos stay the same, the USDT amount changes. The request price is valid for a limited time (the "The price holds until" field; one hour by default). If it has expired, Payin8 cannot approve the request until you update the price. The number of updates is limited.
These two actions do not need a code from the app.
Who can do this#
| Action | Role right |
|---|---|
| See addresses | "See withdrawal wallets" |
| "Add an address", "Rename", "Remove" | "Add withdrawal wallets", "Change withdrawal wallets", "Remove withdrawal wallets" |
| See requests and limits | "See withdrawals", "Open a withdrawal", "See withdrawal limits" |
| "Calculate" | "Calculate a withdrawal" |
| "Create the request" | "Request withdrawals" |
| "Cancel the request", "Update the price" | "Cancel withdrawals", "Refresh the withdrawal rate" |
Adding an address and creating a request require 2FA and are blocked for a while after security changes (see Security).
Cabinet
Deals#
A deal is one pay-in (a client pays you) or one payout (you pay a recipient). Your server creates deals through the API: pay-ins — see Pay-ins, payouts — see Payouts. The cabinet shows them, and you can cancel or dispute some of them.
Pay-in and payout lists#
The Pay-ins and Payouts sections in the menu. The lists refresh by themselves. New deals are on top.
Columns of the "Pay-ins" list: "№", "Invoice" (the order number your server sent at creation), "Created", "Project", "Client", "Amount", "Fee", "To balance", "Status", "Deadline / credited" (a timer until the end of the payment term, or the time of crediting).
Columns of the "Payouts" list: "№ / invoice", "Created", "Project", "Recipient", "Gets", "Fee", "Debited", "Status", "Taken / paid".
Filters#
- "Project" and "Invoice" — above the list;
- "Status" — you can select several;
- "Deal No.";
- "Amount" — "from" and "to";
- period — "From" and "To", or the quick buttons "24 h", "7 days", "30 days"; the period is at most 92 days.
"Reset filters" brings back the whole list.
Statuses#
Pay-in statuses:
| Status in the cabinet | Meaning |
|---|---|
| "Finding an account" | The pay-in is created, Payin8 is finding payment details |
| "Awaiting payment" | Payment details are issued, the client must transfer the money before the term ends |
| "Client reported payment" | The client reported the transfer; waiting for the receipt of funds to be confirmed |
| "Credited" | The payment is confirmed, the money is on the balance |
| "Time is up" | The payment term has expired. While the late confirmation window is open, the pay-in can still be completed: the cabinet shows "Time is up — payment may still arrive" |
| "Canceled" | The pay-in is canceled |
Payout statuses:
| Status in the cabinet | Meaning |
|---|---|
| "Created" | The payout is created |
| "Looking for an executor" | The payout is offered to executors |
| "Being executed" | An executor took the payout and is transferring the money |
| "Checking the receipt" | Reserved: payouts do not move to this status now |
| "Paid" | The money is sent to the recipient |
| "Canceled" | The payout is canceled, the frozen money returned to the balance |
The "Waits for money" mark on a payout means the balance does not have enough money and the payout waits for a top-up (if the "Payout without funds on the balance" rule says so). Other marks can appear next to the status, for example "Dispute", "Late confirmation", "Amount changed", "Partial", "Reversed". How these statuses look in the API: Statuses.
Deal card#
Click a deal in the list. The card opens on the side; its title is "Pay-in № …" or "Payout № …".
The "Deal" tab:
- Pay-in: "Money" ("Requested", "Client paid", "Fee", "To the balance"), "Times" ("Created", "Pay until", "Money arrived", "Completed"), "How the client pays" (account type CVU, CBU or Alias, "Account", "Owner", "CUIT / document", "Bank"), "Client" ("Client id", "Name", "Email", "IP" — what your server sent), "Metadata", "Payment link" (see below).
- Payout: "Money" ("Recipient gets", "Fee", "Debited from the balance", "Frozen on the balance" or "Returned to the balance"), "Recipient", "Execution and receipts" ("Taken by an executor", "Paid", transfer receipts), "Metadata".
- "Invoice numbers" — all order numbers the deal answers for: the first one and those added by repeated client requests.
- If the client paid a different amount, the card warns: "The client paid another amount" — the credit is based on the amount actually received.
- If a payout is executed partially, the card shows how much was executed and how much returned to the balance.
- If the deal had a dispute — the "Dispute" block with the "Go to the dispute" link.
The "Progress" tab — the deal history step by step, with times.
The "Webhooks" tab — all events of this deal sent to your project address: "Open the deliveries of this deal" (see Webhooks).
Payment link. For a pay-in that the client pays on the Payin8 payment page, the card has a "Payment link" block and an "Open" button. Send the link to the client if they lost the page; it works while the pay-in is open.
Your server can also get deal receipts and other files through the API — see Files.
What you can do from the cabinet#
Buttons in the card header appear only when the action is possible and your role has the right.
"Cancel the pay-in". Possible while the pay-in is in the "Finding an account" or "Awaiting payment" status, but the payment details are not yet shown to the client. After cancellation, the client can no longer pay the pay-in.
"Cancel the payout". Possible while the payout is in the "Created" or "Looking for an executor" status, that is, no executor has taken it yet. The frozen money returns to the balance.
In the confirmation window, you can give a reason and must type the word "confirm". While a dispute is open on a deal, you cannot cancel it.
"Open a dispute". See Disputes.
You can also cancel pay-ins and payouts through the API — see Pay-ins and Payouts.
Who can do this#
| What | Role right |
|---|---|
| Lists and cards | "See deals", "Open a deal" |
| The "Progress" tab | "See the deal history" |
| Cancellation | "Cancel deals" |
| Payout receipts | "Download files" |
| Dispute | "See disputes", "Open disputes" |
The system role "Operator" can cancel deals and work with disputes; "Viewer" can only view. Canceling a deal does not need a code from the app.
Cabinet
Disputes#
A dispute is a request to Payin8 when something is wrong with a deal: the client paid but the pay-in is not credited, the amount is wrong, the recipient did not get the payout. Payin8 reviews and resolves the dispute. While a dispute is open, the deal's terms are paused and the deal cannot be canceled.
You can also open and read disputes through the API — see Disputes.
When you can open a dispute#
The "Open a dispute" button appears in the deal card (Pay-ins or Payouts → deal) if:
- the deal has no open dispute;
- the pay-in is in the "Awaiting payment", "Client reported payment", "Time is up" or "Credited" status, or "Canceled" after payment details were assigned to it;
- the payout is in the "Being executed" or "Paid" status;
- the dispute term has not expired: by default, 7 days from deal creation. The term in effect is the "Time to open a dispute on a deal" rule (see Rules). If the term has passed, the cabinet shows until when the dispute could have been opened.
How to open one#
- Open the deal and click "Open a dispute".
- Choose a "Reason":
- for a pay-in — "The client paid, but the pay-in is not completed", "The amount is wrong", "Suspected fraud", "Other";
- for a payout — "The recipient did not get the money", "Suspected fraud", "Other".
- "Comment" — what happened, what the client says, what you expect. Up to 4000 characters; mandatory for the "Other" reason.
- For a pay-in — "How much the client paid" (optional, the amount from the client's receipt).
- Attach files: for a pay-in — "Client’s receipt", for any deal — "Other files". Up to 10 files in total; JPEG, PNG, WebP or PDF, each up to 10 MB.
- Click "Open a dispute".
If a dispute on the deal is already open (for example, someone opened it at the same time as you), your comment is added to it.
Tip
The more precise the evidence, the faster the review: the client's transfer receipt with the amount, time and operation number, a bank statement, the conversation with the client.
Dispute list#
The Disputes section in the menu. Tabs "Open", "Closed", "All"; the "Direction" filter (pay-in or payout).
Columns: "Deal", "Reason", "Opened by", "Opened", "Status", "Outcome", "Last message". The number of new messages is marked in the dispute row.
Not only merchants open disputes: Payin8 can also open a dispute on your deal — for example, if a payout has been in progress for too long. Such disputes appear in the same list.
How to reply#
Open the dispute. The card shows the deal ("Open the deal"), the reason, who opened it and when, and the "Messages" feed.
To reply, fill in the "Reply" block: "Message" (up to 4000 characters) and, if needed, "Files" (up to 10 files), then click "Send". Files are attached to the message text.
Payin8 and the deal's executor read the message and the files.
How a dispute closes#
- A pay-in dispute closes by itself when the executor confirms that the money arrived ("Confirming the pay-in closes the dispute by itself."). A payout dispute closes by itself when the executor attaches the transfer receipt. The exception is a payout dispute that waits for a support decision: the card then says "The dispute waits for a decision of support: a receipt no longer closes it.", and only a Payin8 decision closes it.
- Otherwise, Payin8 closes the dispute with its decision. The outcome is shown in the column and in the card, for example: "Left as it is", "The deal is completed", "The deal is canceled, the money went back", "The completed deal is canceled", "The amount is changed".
A dispute decision can change the money on the balance — you see it in the statement (for example, "Pay-in credit canceled by a dispute" or "Payout returned by a dispute"). A closed dispute does not accept new messages.
There is no separate deadline for replies in a dispute, and a dispute does not close by itself when time passes. Answer Payin8's questions as fast as you can: the decision time depends on it.
Who can do this#
| Action | Role right |
|---|---|
| See disputes and messages | "See disputes" |
| "Open a dispute" | "Open disputes" |
| "Send" a message | "Write in a dispute" |
| Attach files | "Upload files" |
The system role "Operator" can open disputes and reply in them, but it does not have the "Upload files" right — files can be attached by the owner or by a member with a custom role that has this right. "Viewer" can only read.
Cabinet
Team and roles#
Each member has their own sign-in and their own role. The role defines which sections are visible and which actions are available.
Team#
Organization → Team lists everyone who has access to the cabinet: "E-mail", "Name", "Role", "Status", "Second factor", "Last sign-in", "Added". Filters: status, role, "E-mail starts with".
Member statuses: "Invited", "Active", "Disabled", "Removed".
Inviting a member#
- Team → "Invite".
- Enter "E-mail", "Name" (optional) and "Role".
- Click "Create invitation" and confirm with a code from the app.
- The cabinet shows the "Invitation link" and the "Valid until" term. The link is shown once — copy it and give it to the member yourself, in person, not in a shared chat: it gives access to the cabinet.
By default, the link is valid for 72 hours. If the member did not make it in time, open them in the list and click "Send the invitation again" — a new link appears and the previous one stops working. What the member does with the link: Invitation.
You cannot grant a role wider than your own rights. Only an owner can grant the owner role.
Actions with a member#
Open the member in the list. Tabs: "Member" and "Sessions" (where they are signed in now).
| Action | What happens |
|---|---|
| "Change" | Name and role |
| "Disable" | All sessions of the member end at once. The member stays in the team; you can restore access with the "Enable" button. A reason is required |
| "Reset second factor" | The member sets up 2FA again at the next sign-in; their sessions end, and sensitive actions are blocked for them for a while (see Security). A reason is required |
| "End all sessions" | The member has to sign in again on all devices |
| "Password link" | A one-time link for a new password (valid for 30 minutes by default). The cabinet shows it once — give it to the member yourself. The current password works until a new one is set. A reason is required |
| "Remove" | The member loses access for good. The record stays in the activity log |
All actions except "End all sessions" are confirmed with a code from the app. You cannot disable or remove yourself or reset your own 2FA, and you cannot act on a member with wider rights than yours. The organization must always keep at least one active owner.
Roles#
Organization → Roles shows what each role sees and can do. Columns: "Name", "Code", type (system, custom, owner), "Rights", "Second factor" ("required" or "not required"), "Members".
System roles cannot be changed:
| Role | What it can do |
|---|---|
| "Owner" | Everything in the merchant cabinet. 2FA is mandatory |
| "Operator" | Sees everything except the activity log, team, roles and API keys. Cancels deals, opens disputes and replies in them (without uploading files), sends webhook events again |
| "Viewer" | View only — the same as "Operator", without actions |
Custom role. "New role":
- "Code" — lowercase latin letters, digits and
_, starts with a letter, 2–32 characters (the cabinet converts uppercase letters to lowercase); - "Name" — up to 60 characters; "Description" — optional;
- "Rights" — select the ones you need. Rights are grouped by section and split into "View" and "Change"; rights marked "Needs a fresh code from the app" are confirmed with a code on every action.
You cannot grant rights you do not have yourself. If a role has at least one right that needs a code from the app, 2FA is mandatory for it. You can change or delete only a custom role; you can delete only a role with no members. Creating, changing and deleting roles are confirmed with a code from the app. Payin8 can switch off custom roles.
Activity log#
Organization → Activity log shows who did what in the cabinet: sign-ins, team and role changes, issuing and revoking keys, secrets shown, project and rule changes, access denials and more.
- Columns: "Time", "Who", "Action", "Object", "Result" ("done", "denied", "error"), "IP".
- Filters: "Category" ("Sign-in", "Security", "Money", "Requests", "Access denied", "Secrets shown", "Data read"), "Action code" and a period of up to 92 days.
- In an entry — "Details": "Reason", "Before", "After", "More".
Actions of API keys are marked "key", actions of Payin8 staff are marked "platform".
Who can do this#
| What | Role right |
|---|---|
| See the team and sessions | "See the team", "Open a team member", "See sign-in sessions" |
| "Invite", "Send the invitation again" | "Invite team members" |
| "Change", "Disable", "Enable", "Remove" | "Change team members", "Disable team members", "Enable team members", "Remove team members" |
| "Reset second factor", "Password link", "End all sessions" | "Reset the second factor", "Send a password reset link", "End sign-in sessions" |
| Roles | "See roles", "Create roles", "Change roles", "Delete roles" |
| Activity log | "See the activity log", "Open a log entry" |
Team management requires 2FA. After security changes, inviting members with a role that gives more than view access is blocked for a while (see Security).
Cabinet
Payment page#
The Payin8 payment page is where the client sees the payment details and pays a pay-in by bank transfer. Your server gets the link to it when it creates a pay-in (see Pay-ins). In the cabinet, you set up how the page looks and where the client returns after payment.
Where to set it up#
There are settings on two levels:
- for all projects — Organization → Profile and rules, the "Default payment page" block. An empty field means the platform default;
- for one project — Connection → Projects → project → "Payment page" tab. An empty field is taken from the organization settings.
Next to each value, the cabinet shows where it comes from: "from the organization" or "platform default". Click "Edit", fill in the fields and save — with a code from the app.
What you can set up#
| Field | Rules |
|---|---|
| "Shop name for the client" | 1 to 60 characters. If no name is set for the project or the organization, the page shows the project name |
| "Logo" | PNG, WebP or JPEG; SVG is not accepted. By default, the logo file is at most 512 KB. You can remove an uploaded logo: for the organization — "Remove the logo", for a project — "Use the organization logo" |
| "Main colour" | As #RRGGBB. Button text is white, so the colour's contrast with white must be at least 3:1 — the cabinet does not accept a colour that is too light |
| "Support link" | An https:// address without a user name, up to 2048 characters |
| "Support e-mail" | An e-mail address |
| "Return to your site": "After a successful payment", "After a failed payment", "«Back» button" | https:// addresses without a user name, up to 2048 characters |
| "Automatic return" | 0 to 30 seconds: how many seconds after a successful payment the page returns the client to your site by itself; 0 — the client returns only with the button. If not set — the platform default, 5 seconds |
A return address sent with the pay-in through the API takes precedence over the address from the cabinet.
Next to the settings and in the edit form there is the "Sketch of the page header": how the name, logo, button colour and support link will look.
The page language is set by the "Language of the payment page" rule ("as the pay-in", "Spanish", "English"), and whether the client receipt is mandatory — by the "Client receipt required" rule (see Rules).
What the payer sees#
- While Payin8 is finding payment details — a waiting screen asking not to close the page.
- The amount to transfer, a timer until the end of the payment term, and the payment details: CVU or CBU, alias, account owner, CUIT/CUIL, bank, order number — with copy buttons. A short instruction: transfer the exact amount in one transfer before the term ends.
- A field for the transfer receipt — mandatory or optional, depending on the "Client receipt required" rule.
- A button for the client to report the transfer, and a button to cancel the payment.
- After that — the payment check screen; then the successful payment screen with a return to your site, or the expired term screen.
The page shows your name, logo, colour and support links. The client can switch the language (Spanish or English).
Payment link#
For each pay-in paid on the payment page, the deal card has a "Payment link" block with an "Open" button. If the client lost the page, send them this link: it works while the pay-in is open.
Your own domain#
Payin8 connects and verifies the domains the payment page opens on; the merchant cabinet has no such setting. If you want the payment page to open on your domain, contact Payin8 support. Payin8 tells you which DNS records to create: a TXT record to confirm domain ownership and records that point the domain to Payin8 addresses. After you create the records, Payin8 checks them and activates the domain.
By default, you cannot embed the payment page in a frame on your site. Payin8 sets the addresses allowed to embed it for each project — contact Payin8 support.
Who can do this#
| Action | Role right |
|---|---|
| See the payment page settings | "See the payment page settings" |
| "Edit" | "Change the payment page settings" (with a code from the app) |
| Logo upload | "Upload files" |
Cabinet
Security#
Hold after security changes#
If someone gets access to your account, the first thing they will try is to issue a key, change the webhook address or withdraw money. So after some security changes, the cabinet temporarily blocks the most sensitive actions for that member. By default, for 24 hours (Payin8 sets the term).
What starts the hold:
- sign-in with a recovery code;
- a password change with a new password link;
- a 2FA reset by the cabinet owner (the hold starts at once), and turning 2FA on again after a reset or after turning it off;
- the first time 2FA is turned on by a member invited from the cabinet;
- a team member granting the owner role.
These do not start the hold: a regular password change in the profile (with the current password), moving 2FA to a new phone, issuing new recovery codes. An owner created by Payin8 does not get a hold when turning on 2FA for the first time — they can issue a key, set up the webhook and add a withdrawal address at once.
What is blocked during the hold:
| Action | Where in the cabinet |
|---|---|
| Adding a withdrawal address | Money → Wallets → "Add an address" |
| Creating a withdrawal request | Money → Withdrawals → "New withdrawal" |
| Issuing an API key | Connection → API keys → "Issue a key" |
| Changing an API key and replacing its secret | Key card → "Change", "Replace the secret" |
| Changing the webhook and replacing the signing secret | The project's "Webhook" tab |
| Inviting a member with a role that gives more than view access | Organization → Team → "Invite" |
When you try, the cabinet shows "Sensitive actions are paused after a security change until …" with the exact end time. Everything else, including revoking keys, works as usual. You cannot lift the hold early from the cabinet.
Tip
Plan your integration with the hold in mind: if a member's 2FA was reset or they signed in with a recovery code, issuing keys and setting up the webhook become available to them only when the hold ends (by default, after a day). Other members with the needed rights and no hold can do it at once.
What to do after a leak#
- An API key secret leaked — revoke the key at once (key card → "Revoke"; no code from the app needed) or all keys of the project ("Revoke all"). Then issue a new key.
- A webhook signing secret leaked — replace it ("Webhook" tab → "Replace the secret"). The previous secret keeps signing together with the new one for a while.
- A password or a phone with the app leaked — end all your sessions ("Profile and security" → "Sign out on other devices" or the "Account" menu → "Sign out everywhere"), change the password and move 2FA. If you lost access to the account, ask the owner to disable it, reset 2FA and issue a password link. If you are the owner, contact Payin8 support.
- Check suspicious actions in Organization → Activity log (categories "Security", "Secrets shown", "Access denied").
Storing secrets#
- The API key secret and the webhook signing secret are shown once. Put them in your server's secret store right away — not in code, not in a repository and not in messages.
- Use a separate key for each project and purpose. By default, a project can have at most 2 active keys — enough to replace a secret without downtime.
- Give a key only the rights it needs. Money rights ("Create payouts", "Cancel payouts") go only to the key that actually creates payouts.
- Replace secrets on a schedule: "Replace the secret" with overlap ("one more hour", "one more day", "seven more days") lets you switch your server without stopping.
- Check the signature of every incoming webhook (see Webhooks) and do not trust requests without it.
- Invitation links and password links give access to the cabinet: hand them over in person, not in a shared chat.
- Keep recovery codes where you keep passwords, separately from your phone.
IP address list#
- Restrict the addresses of every key: then a stolen secret is useless from someone else's server.
- To create payouts, and pay-ins that return payment details right in the response, an address list is mandatory.
- Enter exact server addresses or narrow ranges. The cabinet does not accept ranges wider than
/24for IPv4 and/56for IPv6. - When you change servers, first add the new addresses to the key ("Change"), switch the traffic, and only then remove the old ones.
Team#
- Give members minimal roles: "Viewer" to view, "Operator" or a custom role to work with deals and disputes.
- Disable access for members who leave at once ("Disable" or "Remove").
- Keep more than one owner with 2FA set up in the organization, so you do not lose control of the cabinet.
Cabinet
Pre-launch checklist#
Go through this list before you let real clients in.
Access#
- The owner has 2FA turned on, and the recovery codes are saved in a safe place.
- The organization has more than one member who can manage the cabinet, or you know how to restore access through Payin8 support.
- Members are invited with the minimal roles they need (see Team and roles).
- "Contacts" in Organization → Profile and rules are filled in — Payin8 uses them to contact you.
Project#
- The project is in the "Active" status.
- On the "Methods and limits" tab, the directions you need are on, and the amount limits fit your orders.
- A tariff is set for each direction that is on — there is no "Tariff not set" warning.
- The project rules are checked: "Language of the payment page", "Client receipt required", "Late confirmation of pay-ins", "Payout without funds on the balance".
API key#
- The key is issued for the right project; the ID and the secret are in the server's secret store.
- The key has only the rights it needs; money rights only if the key creates payouts.
- "Addresses" list the IP addresses of your servers (mandatory for payouts and for pay-ins that return payment details in the response).
- The server signs requests correctly: a test request passes without signature errors (see Request signing, Errors).
- Retries of deal creation requests are handled safely (see Idempotency).
Webhooks#
- The webhook address is set, "Send events" is on, and the events you need are selected.
- The signing secret is saved, and the server checks the signature of every request (see Webhooks).
- "Send a check" sends an event, and in Connection → Webhook delivery it has the "Delivered" status.
- The handler answers
2xxfast and correctly accepts a repeat of the same event. - There is a plan for an outage: how to find "Failed" events and send them again.
Payment page#
- The shop name, logo, colour, and support link or e-mail are set.
- The "After a successful payment" and "After a failed payment" return addresses are set (or your server sends them with each pay-in).
- If you need your own domain or frame embedding, it is agreed with Payin8 support and the domain is activated.
Money#
- You know how the balance for payouts is topped up: pay-in credits or a USDT top-up (Money → Top-up).
- A withdrawal address is added in advance — you can use it only after a pause (24 hours by default).
- Withdrawal limits and fees are taken into account (the "What you can withdraw" block in the withdrawal wizard).
First deal#
- A small pay-in went through all steps: created, the client paid, the status is "Credited", the money is in "Balance and statement".
- Your server received the "Pay-in: account issued" and "Pay-in credited" webhooks.
- If you make payouts — a test payout reached the "Paid" status, and the "Payout executed" webhook was received.
- The team knows where to look at deals and how to open a dispute (see Deals, Disputes).
API
API overview#
The Payin8 merchant API is the interface for your server: create a pay-in or a payout by bank transfer, get the state of a deal, the balance and the method terms, upload a file to a deal, open a dispute. Payin8 reports deal changes with webhooks.
Only your server calls the API: every request is signed with the API key secret (see Authentication). Do not call the API from a browser or a mobile app, and do not send the key secret there.
Integration step by step#
- Get a key. In the cabinet, issue an API key for the project with the rights you need and the IP addresses of your server; save the key ID
mk_…and the secretms_…(see API keys). - Sign a test request. Copy the ready-to-use functions, put the key and the secret into the environment variables and call
GET /v1/balance: the answer200means the signature works. If not, compare your values with the worked example. - Check the terms.
GET /v1/methodsshows which methods and directions are on for the project, the amount limits and the fees (see Methods). - Accept webhooks. Set the address and the events of the project in the cabinet and save the signing secret
whsec_…(see Webhooks). Your handler checks the signature and answers2xxat once (see How to respond). The "Send a check" button sendswebhook.ping: it lets you test the handler before the first deal. - Create a pay-in.
POST /v1/payinswith yourinvoiceId, the amount, the client and the modeflow(see Create a pay-in). Withflow: requisite, show the client therequisiteand theamountfrom the answer or from thepayin.assignedwebhook; withflow: widget, send the client topaymentUrl. - Get the result. The outcome comes in the
payin.completedorpayin.failedwebhook; you can always read the current state withGET /v1/payins/{id}or by your number (see Get by number). - Handle failures. After a timeout or a
5xx, repeat the creation with the sameinvoiceId: a second deal is not created (see Idempotency).
Before going live, go through the checklist.
Base URL and version#
https://api.payin8.ioAll paths start with the version: /v1/…, for example POST https://api.payin8.io/v1/payins. The current and only version is v1; the version is part of the signed path.
Request and response format#
- Request and response bodies are JSON in UTF-8. Send a request with a body with the
Content-Type: application/jsonheader. The exception is a file upload: the body ofPOST /v1/filesis the file bytes themselves (see Files). - Fields that are not in the endpoint description are not accepted: a request with an extra field gets
400 validation_failed("property … should not exist"). - String values are trimmed of leading and trailing spaces; an empty string after trimming counts as a field that was not sent.
- An error response is always
{ "code", "message", "details"? }(see Errors).
Headers present in every response:
| Header | Value |
|---|---|
X-Request-Id |
The request ID on the Payin8 side (UUID). Include it when you contact support. |
X-Client-Request-Id |
Your own X-Request-Id, if you sent one and it consists of 1–64 characters A–Z a–z 0–9 _ -. Payin8 does not use it as its own ID; it only returns it. |
Cache-Control |
no-store (for the payout receipt download — private, no-store): API responses are not cached. |
Money#
- Amounts are decimal strings with a dot:
"15000.00". JSON numbers are not accepted (400 validation_failed). - In a request: the amount is greater than zero, has at most 13 digits in the integer part, and no more decimal places than the currency has.
ARShas 2:"15000","15000.5"and"15000.50"are valid,"15000.505"is not. - In a response, an amount always has the full number of decimal places of the currency:
"15000.00". - The currency is an uppercase code:
ARS. The payment method isbank_transfer(bank transfer). - Fee percentages are strings:
"2.5"means 2.5%.
Time#
- All points in time in responses and webhooks are ISO 8601 in UTC with milliseconds:
"2026-11-19T16:08:12.277Z". - The
createdFromandcreatedTolist filters accept ISO 8601 (2026-11-19T00:00:00Z). - The
X-Timestampsignature header is Unix time in seconds (10 digits).
Identifiers#
| What | Format | Set by |
|---|---|---|
id of a deal, file, dispute, webhook event |
UUID v4, for example 3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44 |
Payin8 |
invoiceId |
1–64 characters: latin letters, digits, . _ : - |
You. Unique within the merchant, separately for pay-ins and for payouts |
customer.id |
1–128 printable ASCII characters without spaces | You: your client ID |
version |
An integer that grows with each change of the deal | Payin8 |
invoiceId is your order or request number; it drives the idempotency of creation and the deal lookup (GET /v1/payins/by-invoice/{invoiceId}).
How a pay-in works#
- Your server creates a pay-in:
POST /v1/payinswith the amount, the client and the pay-in mode (flow). - Payin8 finds an executor and their bank account (payment details). The pay-in moves from
createdtoawaiting_payment, and thepayin.assignedwebhook arrives. The payment term is theexpiresAtfield. - The client transfers the money to the payment details: with
flow: requisiteyou show the payment details and theamountto the client, withflow: widgetthe Payin8 payment page at thepaymentUrllink does it. - The receipt of funds is confirmed — the pay-in is
completed, and thepayin.completedwebhook arrives.net=amount−feeis credited to the balance. - If there was no payment in time or no executor was found —
expiredorcanceled, and thepayin.failedwebhook.
Details: Pay-ins and Deal statuses.
How a payout works#
- Your server creates a payout:
POST /v1/payoutswith the amount and the recipient's account.totalDebit=amount+feeis held on the balance, and the payout is offered to executors (offered). - An executor takes the payout (
in_progress), transfers the money to the recipient and attaches a receipt. - The payout is
completed, and thepayout.completedwebhook arrives; you can download the receipt (GET /v1/payouts/{id}/receipts/{fileId}). - If nobody took the payout in time, it was canceled, or the transfer is impossible —
canceled, thepayout.failedwebhook, and the held amount returns to the balance.
Details: Payouts.
Pay-in modes#
The flow field sets the mode when a pay-in is created.
flow |
How the client gets the payment details | What you need |
|---|---|---|
requisite |
The payment details come in the API response (requisite) and in the payin.assigned webhook; you show them to the client on your side. |
An IP list on the API key (otherwise 403 ip_allowlist_required). |
widget |
The response has a paymentUrl link to the Payin8 payment page. The client sees the payment details there, can mark "I paid", attach a receipt or cancel the pay-in. |
A configured project payment page (see Payment page). If it is not available, creation returns 422 feature_unavailable with details.feature: "widget". |
In both cases, the pay-in outcome comes by webhook and is visible in GET /v1/payins/{id}.
Endpoint list#
Each endpoint needs its own key right (see Key rights).
| Method and path | Key right | What it does |
|---|---|---|
POST /v1/payins |
merchant_api.payins.create |
Create a pay-in |
GET /v1/payins |
merchant_api.payins.read |
List pay-ins |
GET /v1/payins/{id} |
merchant_api.payins.read |
Get a pay-in by id |
GET /v1/payins/by-invoice/{invoiceId} |
merchant_api.payins.read |
Get a pay-in by your number |
POST /v1/payins/{id}/cancel |
merchant_api.payins.cancel |
Cancel a pay-in |
POST /v1/payouts |
merchant_api.payouts.create |
Create a payout |
GET /v1/payouts |
merchant_api.payouts.read |
List payouts |
GET /v1/payouts/{id} |
merchant_api.payouts.read |
Get a payout by id |
GET /v1/payouts/by-invoice/{invoiceId} |
merchant_api.payouts.read |
Get a payout by your number |
GET /v1/payouts/{id}/receipts/{fileId} |
merchant_api.payouts.read |
Download a payout receipt |
POST /v1/payouts/{id}/cancel |
merchant_api.payouts.cancel |
Cancel a payout |
GET /v1/balance |
merchant_api.balance.read |
Merchant balance |
GET /v1/methods |
merchant_api.methods.read |
Project methods: limits and fees |
POST /v1/files |
merchant_api.files.create |
Upload a file to a deal |
POST /v1/disputes |
merchant_api.disputes.create |
Open a dispute |
GET /v1/disputes |
merchant_api.disputes.read |
List disputes |
GET /v1/disputes/{id} |
merchant_api.disputes.read |
Get a dispute by id |
POST /v1/disputes/{id}/evidence |
merchant_api.disputes.create |
Add evidence to a dispute |
A request to a path that is not in the list gets 404 route_not_found.
API
Authentication#
Every API request, including GET, is signed with the project's API key. The signature is HMAC-SHA256 of the canonical request string; the key secret is never sent in the request.
API key#
You create a key in the merchant cabinet for a specific project (see API keys). A key has two parts:
| Part | Example | Where it is used |
|---|---|---|
| Key ID | mk_7k2m9q4x8p1r5t3v6w0y2z4b8c — mk_ and 26 characters |
The X-Api-Key header in every request |
| Secret | ms_dGhpcy1pcy1hbi1leGFtcGxlLXNlY3JldC1vbmx5LTA — ms_ and 43 characters |
The HMAC key for the signature. Shown once when the key is created; keep it on your server only |
A key belongs to one project and sees only the deals, files and disputes of that project: a deal of another project does not exist for it (404 not_found). The exception is the balance: GET /v1/balance shows the merchant balance, shared by all of the merchant's projects.
A revoked key, a key whose term after rotation has expired, and a key that does not exist all get the same response: 401 api_key_invalid.
Request headers#
| Header | Value |
|---|---|
X-Api-Key |
The key ID mk_… |
X-Timestamp |
The send time in Unix seconds (10 digits): 1795104000 |
X-Nonce |
A one-time string of 16–64 characters A–Z a–z 0–9 _ -, new for every request. A convenient choice is 32 random hex characters |
X-Signature |
v1= and the 64 hex characters of the signature |
Content-Type |
For requests with a body: application/json; for POST /v1/files — the file type. A JSON body with a different Content-Type is not read, and the request gets 401 signature_invalid |
If any of the four signature headers is missing, the request gets 401 signature_missing.
Canonical string#
You sign a string of six lines joined with the newline character \n (no trailing \n):
v1
<METHOD>
<path and query>
<X-Timestamp>
<X-Nonce>
<hex SHA-256 of the body><METHOD>— the method in uppercase:GET,POST.<path and query>— the path starting with/v1/, and the query string exactly as it is sent in the request:/v1/payins?status=completed&limit=20. Parameters are not sorted or re-encoded; without a query string, use the path alone. The host and the scheme are not part of the string.<hex SHA-256 of the body>— the lowercase SHA-256 of the raw body bytes. Sign exactly the bytes you send: serialize the JSON once and send that same string. For a request without a body, use the hash of the empty stringe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.
The signature:
X-Signature = "v1=" + hex( HMAC-SHA256( key = the whole "ms_…" secret in UTF-8, message = the canonical string ) )The HMAC key is the whole secret string including the ms_ prefix, with no decoding.
Worked example#
The key and the secret are fictional, from the table above. The request:
POST /v1/payins
X-Timestamp: 1795104000
X-Nonce: 3f9c2a7d1b6e4f08a5c3d2e1f0a9b8c7
Content-Type: application/json
{"invoiceId":"inv-100501","amount":"41400.00","currency":"ARS","method":"bank_transfer","flow":"requisite","customer":{"id":"client-42"}}SHA-256 of the body:
30c3d1602c2e005c5f61912a5e56f9654cfa6b4488ebc502d77e0df913ae6122The canonical string:
v1
POST
/v1/payins
1795104000
3f9c2a7d1b6e4f08a5c3d2e1f0a9b8c7
30c3d1602c2e005c5f61912a5e56f9654cfa6b4488ebc502d77e0df913ae6122The signature header:
X-Signature: v1=c4acc4e91400077869ed47cba8b1b4291da546d9e03508505f61a0dd182a8f19For GET /v1/payins?status=completed&limit=20 with the same X-Timestamp and X-Nonce, the signature is v1=25c4c4411ddfd6bebbd2bde7c14419dd54c606c27c0cf39f26066362d2896e65. Check your implementation against these values.
Timestamp and nonce#
- Time window.
X-Timestampmust differ from the Payin8 server time by no more than the allowed window in either direction (300 seconds by default); otherwise you get401 timestamp_out_of_window. Thedetails.serverTimeof this error is the server time in Unix seconds: use it to check your server clock. Keep your clocks synchronized (NTP). - Nonce. You cannot use an
X-Noncetwice with the same key: a repeat gets401 nonce_replayed. Payin8 stores the nonce only after the request signature has matched, so a request with a wrong signature does not use up the nonce. - Retrying a request. If you retry a request (for example, after a dropped connection), sign it again: a new
X-TimestampandX-Nonce, a new signature. A safe retry of creation relies oninvoiceId(see Idempotency), not on the nonce.
Order of checks#
Payin8 checks a request in this order and responds with the first error it finds:
- The four signature headers are present; the
X-Nonceformat. - The key: it exists, it is active, it is a merchant API key.
X-Timestampis within the window.- The signature.
X-Noncehas not been used.- The sender address is in the key's IP list (if the list is set).
- The merchant and the project are active.
- The key has the right for this endpoint.
- For payout creation — the key has a non-empty IP list (see below).
- The key's request rate limit.
Errors of steps 1–5 are the same for any key and reveal nothing about the key; the address is checked only for a request with a valid signature. The IP list requirement for a pay-in with flow: requisite is checked later, while the request body is processed.
Key IP list#
A key can have a list of allowed sender addresses: single addresses or CIDR ranges (IPv4 and IPv6, up to 20 entries). You set the list in the cabinet (see API keys and Security).
- If the list is set, a request from another address gets
403 ip_not_allowed. - Without a non-empty list, the key cannot create payouts and pay-ins with
flow: requisite(this is the default list of operations): such requests get403 ip_allowlist_required, with the operation code indetails.code(merchant_api.payouts.createormerchant_api.payins.create:requisite). Other endpoints work without the list.
Key rights#
A key is given a set of rights; a request to an endpoint the key has no right for gets 403 permission_denied with the right code in details.code.
| Right | Endpoints |
|---|---|
merchant_api.payins.create |
POST /v1/payins |
merchant_api.payins.read |
GET /v1/payins, GET /v1/payins/{id}, GET /v1/payins/by-invoice/{invoiceId} |
merchant_api.payins.cancel |
POST /v1/payins/{id}/cancel |
merchant_api.payouts.create |
POST /v1/payouts |
merchant_api.payouts.read |
GET /v1/payouts, GET /v1/payouts/{id}, GET /v1/payouts/by-invoice/{invoiceId}, GET /v1/payouts/{id}/receipts/{fileId} |
merchant_api.payouts.cancel |
POST /v1/payouts/{id}/cancel |
merchant_api.balance.read |
GET /v1/balance |
merchant_api.methods.read |
GET /v1/methods |
merchant_api.files.create |
POST /v1/files |
merchant_api.disputes.create |
POST /v1/disputes, POST /v1/disputes/{id}/evidence |
merchant_api.disputes.read |
GET /v1/disputes, GET /v1/disputes/{id} |
Only the merchant owner or a team member with a dedicated right can grant payout rights (payouts.create, payouts.cancel) to a key.
Ready-to-use functions#
Signing and calling functions that you can copy into your project. The key, the secret and the base URL come from the PAYIN8_KEY_ID, PAYIN8_SECRET and PAYIN8_BASE_URL environment variables; the default values in the code are fictional. The examples in the other sections call these functions: payin8 / payin8_file (cURL), payin8Request (Node.js), payin8_request (Python and PHP).
# Payin8 API: request signing and calling. Requires bash, curl and openssl.
PAYIN8_BASE_URL="${PAYIN8_BASE_URL:-https://api.payin8.io}"
PAYIN8_KEY_ID="${PAYIN8_KEY_ID:-mk_7k2m9q4x8p1r5t3v6w0y2z4b8c}"
PAYIN8_SECRET="${PAYIN8_SECRET:-ms_dGhpcy1pcy1hbi1leGFtcGxlLXNlY3JldC1vbmx5LTA}"
# payin8_sign METHOD PATH_AND_QUERY TIMESTAMP NONCE BODY_SHA256 → prints "v1=<64 hex>"
payin8_sign() {
local canonical
canonical=$(printf 'v1\n%s\n%s\n%s\n%s\n%s' "$1" "$2" "$3" "$4" "$5")
printf 'v1=%s' "$(printf '%s' "$canonical" \
| openssl dgst -sha256 -hmac "$PAYIN8_SECRET" -r | cut -d' ' -f1)"
}
# payin8 METHOD PATH_AND_QUERY [JSON_BODY] — a JSON request; prints the response as is
payin8() {
local method="$1" path="$2" body="${3-}"
local ts nonce hash
ts=$(date +%s)
nonce=$(openssl rand -hex 16)
hash=$(printf '%s' "$body" | openssl dgst -sha256 -r | cut -d' ' -f1)
local args=(-sS -X "$method" "$PAYIN8_BASE_URL$path"
-H "X-Api-Key: $PAYIN8_KEY_ID" -H "X-Timestamp: $ts" -H "X-Nonce: $nonce"
-H "X-Signature: $(payin8_sign "$method" "$path" "$ts" "$nonce" "$hash")")
if [ -n "$body" ]; then
args+=(-H "Content-Type: application/json" --data-binary "$body")
fi
curl "${args[@]}"
}
# payin8_file METHOD PATH_AND_QUERY FILE CONTENT_TYPE — the request body is the file bytes
payin8_file() {
local method="$1" path="$2" file="$3" type="$4"
local ts nonce hash
ts=$(date +%s)
nonce=$(openssl rand -hex 16)
hash=$(openssl dgst -sha256 -r < "$file" | cut -d' ' -f1)
curl -sS -X "$method" "$PAYIN8_BASE_URL$path" \
-H "X-Api-Key: $PAYIN8_KEY_ID" -H "X-Timestamp: $ts" -H "X-Nonce: $nonce" \
-H "X-Signature: $(payin8_sign "$method" "$path" "$ts" "$nonce" "$hash")" \
-H "Content-Type: $type" --data-binary "@$file"
}// Payin8 API: request signing and calling. Node.js 18+ (built-in fetch and crypto).
import { createHash, createHmac, randomBytes } from 'node:crypto';
const BASE_URL = process.env.PAYIN8_BASE_URL ?? 'https://api.payin8.io';
const KEY_ID = process.env.PAYIN8_KEY_ID ?? 'mk_7k2m9q4x8p1r5t3v6w0y2z4b8c';
const SECRET = process.env.PAYIN8_SECRET ?? 'ms_dGhpcy1pcy1hbi1leGFtcGxlLXNlY3JldC1vbmx5LTA';
/** The X-Signature header value: "v1=" + hex(HMAC-SHA256(secret, canonical string)). */
export function signPayin8Request({ secret, method, pathAndQuery, timestamp, nonce, body }) {
const canonical = [
'v1',
method.toUpperCase(),
pathAndQuery,
timestamp,
nonce,
createHash('sha256').update(body).digest('hex'),
].join('\n');
return 'v1=' + createHmac('sha256', secret).update(canonical).digest('hex');
}
/**
* A signed request. body: an object (sent as JSON), a Buffer (sent as is, needs contentType) or undefined.
* Returns { status, headers, body }: body is the parsed JSON, or a Buffer for files.
*/
export async function payin8Request(method, pathAndQuery, body, contentType = 'application/json') {
const raw =
body === undefined ? Buffer.alloc(0) : Buffer.isBuffer(body) ? body : Buffer.from(JSON.stringify(body), 'utf8');
const timestamp = String(Math.floor(Date.now() / 1000));
const nonce = randomBytes(16).toString('hex');
const headers = {
'X-Api-Key': KEY_ID,
'X-Timestamp': timestamp,
'X-Nonce': nonce,
'X-Signature': signPayin8Request({ secret: SECRET, method, pathAndQuery, timestamp, nonce, body: raw }),
};
if (raw.length > 0) {
headers['Content-Type'] = contentType;
}
const res = await fetch(BASE_URL + pathAndQuery, {
method,
headers,
body: raw.length > 0 ? raw : undefined,
});
const isJson = (res.headers.get('content-type') ?? '').includes('application/json');
return {
status: res.status,
headers: Object.fromEntries(res.headers),
body: isJson ? await res.json() : Buffer.from(await res.arrayBuffer()),
};
}# Payin8 API: request signing and calling. Python 3.8+, standard library only.
import hashlib
import hmac
import json
import os
import secrets
import time
import urllib.error
import urllib.request
BASE_URL = os.environ.get("PAYIN8_BASE_URL", "https://api.payin8.io")
KEY_ID = os.environ.get("PAYIN8_KEY_ID", "mk_7k2m9q4x8p1r5t3v6w0y2z4b8c")
SECRET = os.environ.get("PAYIN8_SECRET", "ms_dGhpcy1pcy1hbi1leGFtcGxlLXNlY3JldC1vbmx5LTA")
def sign_payin8_request(secret, method, path_and_query, timestamp, nonce, body):
"""The X-Signature header value: "v1=" + hex(HMAC-SHA256(secret, canonical string))."""
canonical = "\n".join([
"v1",
method.upper(),
path_and_query,
timestamp,
nonce,
hashlib.sha256(body).hexdigest(),
])
return "v1=" + hmac.new(secret.encode("utf-8"), canonical.encode("utf-8"), hashlib.sha256).hexdigest()
def payin8_request(method, path_and_query, body=None, content_type="application/json"):
"""body: a dict (sent as JSON), bytes (sent as is) or None. Returns (status, headers, body)."""
if body is None:
raw = b""
elif isinstance(body, bytes):
raw = body
else:
raw = json.dumps(body, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
timestamp = str(int(time.time()))
nonce = secrets.token_hex(16)
headers = {
"X-Api-Key": KEY_ID,
"X-Timestamp": timestamp,
"X-Nonce": nonce,
"X-Signature": sign_payin8_request(SECRET, method, path_and_query, timestamp, nonce, raw),
}
if raw:
headers["Content-Type"] = content_type
request = urllib.request.Request(BASE_URL + path_and_query, data=raw or None, method=method, headers=headers)
try:
with urllib.request.urlopen(request, timeout=40) as response:
return _answer(response.status, response.headers, response.read())
except urllib.error.HTTPError as error:
return _answer(error.code, error.headers, error.read())
def _answer(status, headers, data):
if "application/json" in headers.get("Content-Type", ""):
data = json.loads(data)
return status, dict(headers), data<?php
// Payin8 API: request signing and calling. PHP 7.4+ with the curl and json extensions.
$PAYIN8_BASE_URL = getenv('PAYIN8_BASE_URL') ?: 'https://api.payin8.io';
$PAYIN8_KEY_ID = getenv('PAYIN8_KEY_ID') ?: 'mk_7k2m9q4x8p1r5t3v6w0y2z4b8c';
$PAYIN8_SECRET = getenv('PAYIN8_SECRET') ?: 'ms_dGhpcy1pcy1hbi1leGFtcGxlLXNlY3JldC1vbmx5LTA';
/** The X-Signature header value: "v1=" + hex(HMAC-SHA256(secret, canonical string)). */
function payin8_sign(string $secret, string $method, string $pathAndQuery, string $timestamp, string $nonce, string $body): string
{
$canonical = implode("\n", [
'v1',
strtoupper($method),
$pathAndQuery,
$timestamp,
$nonce,
hash('sha256', $body),
]);
return 'v1=' . hash_hmac('sha256', $canonical, $secret);
}
/**
* A signed request. $body: an array (sent as JSON), a string (sent as is) or null.
* Returns ['status' => int, 'headers' => array, 'body' => array|string].
*/
function payin8_request(string $method, string $pathAndQuery, $body = null, string $contentType = 'application/json'): array
{
global $PAYIN8_BASE_URL, $PAYIN8_KEY_ID, $PAYIN8_SECRET;
if ($body === null) {
$raw = '';
} elseif (is_string($body)) {
$raw = $body;
} else {
$raw = json_encode($body, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
}
$timestamp = (string) time();
$nonce = bin2hex(random_bytes(16));
$headers = [
'X-Api-Key: ' . $PAYIN8_KEY_ID,
'X-Timestamp: ' . $timestamp,
'X-Nonce: ' . $nonce,
'X-Signature: ' . payin8_sign($PAYIN8_SECRET, $method, $pathAndQuery, $timestamp, $nonce, $raw),
];
if ($raw !== '') {
$headers[] = 'Content-Type: ' . $contentType;
}
$responseHeaders = [];
$ch = curl_init($PAYIN8_BASE_URL . $pathAndQuery);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_HTTPHEADER => $headers,
CURLOPT_POSTFIELDS => $raw,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 40,
CURLOPT_HEADERFUNCTION => function ($ch, $line) use (&$responseHeaders) {
$parts = explode(':', $line, 2);
if (count($parts) === 2) {
$responseHeaders[strtolower(trim($parts[0]))] = trim($parts[1]);
}
return strlen($line);
},
]);
$data = curl_exec($ch);
if ($data === false) {
throw new RuntimeException('Payin8 request failed: ' . curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if (strpos($responseHeaders['content-type'] ?? '', 'application/json') !== false) {
$data = json_decode($data, true, 512, JSON_THROW_ON_ERROR);
}
return ['status' => $status, 'headers' => $responseHeaders, 'body' => $data];
}To check: a GET /v1/balance call must return 200 and your balance.
payin8 GET /v1/balanceconst { status, body } = await payin8Request('GET', '/v1/balance');
console.log(status, body);status, headers, body = payin8_request("GET", "/v1/balance")
print(status, body)$r = payin8_request('GET', '/v1/balance');
echo $r['status'], ' ', json_encode($r['body']), "\n";Authentication errors#
| HTTP | code |
When | What to do |
|---|---|---|---|
401 |
signature_missing |
One of the X-Api-Key, X-Timestamp, X-Nonce, X-Signature headers is missing |
Send all four |
401 |
nonce_invalid |
X-Nonce does not match ^[A-Za-z0-9_-]{16,64}$ |
Fix the nonce generation |
401 |
api_key_invalid |
The key does not exist, is revoked, or its term after rotation has expired | Check the key in the cabinet; issue a new one |
401 |
timestamp_out_of_window |
X-Timestamp is not in the format (10 digits) or is outside the allowed window from the server time (300 s by default); details.serverTime is the server time |
Synchronize the clock and sign the request again |
401 |
signature_invalid |
The signature does not match, or the header is not in the v1=<64 hex> format |
Compare your canonical string with the worked example: the path with the query string, the hash of exactly the body bytes sent, the whole secret |
401 |
nonce_replayed |
This key has already used this X-Nonce |
Use a new nonce for every request |
403 |
ip_not_allowed |
The sender address is not in the key's IP list | Add the address to the key's list or send from an allowed address |
403 |
ip_allowlist_required |
A payout or a pay-in with flow: requisite is created with a key without an IP list; details.code is the operation |
Set an IP list on the key |
403 |
tenant_blocked |
The merchant is blocked | Contact Payin8 support |
403 |
project_disabled |
The key's project is disabled | Contact Payin8 support |
403 |
permission_denied |
The key has no right for the endpoint; details.code is the required right |
Grant the right to the key in the cabinet |
429 |
rate_limited |
The key's per-minute request limit is exceeded; details.retryAfterSec and the Retry-After header give the number of seconds to wait |
Wait and retry with a new signature |
503 |
nonce_store_unavailable |
Request verification is temporarily unavailable | Retry later with a new signature |
API
Pay-ins#
A pay-in is money that the client sends you by bank transfer to the account of a Payin8 executor. How a pay-in works is in the overview; the statuses are in Deal statuses.
Pay-in object#
This is how a pay-in looks in API responses and in the data field of payin.* webhooks.
| Field | Type | Meaning |
|---|---|---|
id |
string (UUID) | The pay-in ID in Payin8 |
object |
string | Always payin |
invoiceId |
string | Your number. In the creation response and in GET …/by-invoice/{invoiceId} — the number from the request; in other responses and in webhooks — the first number of the deal |
invoiceIds |
string[] | All your numbers attached to this pay-in (see Repeat for the same client) |
status |
string | created, awaiting_payment, client_paid, completed, expired, canceled |
final |
boolean | true — the status will not change on its own any more. false — it can change (for example, an expired pay-in can still be confirmed, or a dispute is open on the deal) |
flow |
string | requisite or widget |
method |
string | bank_transfer |
currency |
string | The currency, for example ARS |
requestedAmount |
string | The amount from your request |
amount |
string | The amount to pay while the pay-in is open; the confirmed amount after completed. Can differ from requestedAmount |
fee |
string | null | Your fee on this amount |
net |
string | null | amount − fee: credited to the balance after completed |
customer |
object | { "id", "name" } of the client from the request (name is null if you did not send it) |
paymentUrl |
string | null | The payment page link; only with flow: widget |
requisite |
object | null | The payment details; only with flow: requisite, in the awaiting_payment and client_paid statuses, in the creation response, in GET of a single pay-in and in the payin.assigned webhook. Always null in lists |
requisite.type |
string | cvu or cbu |
requisite.number |
string | The account number, 22 digits |
requisite.alias |
string | null | The account alias |
requisite.holderName |
string | The account holder |
requisite.holderTaxId |
string | null | The holder's CUIT/CUIL, 11 digits |
requisite.bankName |
string | The bank |
expiresAt |
string | null | The payment term; null until an executor is assigned |
failureReason |
string | null | The failure reason for expired and canceled (see Reasons) |
dispute |
object | null | { "id", "status" } of an open dispute on the deal |
returnUrls |
object | { "success", "fail", "back" } from the request (null if you did not send them) |
locale |
string | The payment page language: es or en |
metadata |
object | Your metadata from the request |
test |
boolean | Reserved, currently always false |
version |
integer | The deal version number; grows with each change |
createdAt, updatedAt |
string | Created, updated |
assignedAt |
string | null | An executor was assigned |
clientPaidAt |
string | null | The client marked the payment on the payment page |
completedAt |
string | null | Confirmed |
expiredAt |
string | null | Expired |
canceledAt |
string | null | Canceled |
Endpoints#
POST/v1/payins#
Creates a pay-in. Key right: merchant_api.payins.create. For flow: requisite, the key must have a non-empty IP list.
Request body
| Field | Type | Required | Constraints | Meaning |
|---|---|---|---|---|
invoiceId |
string | yes | 1–64 characters A–Z a–z 0–9 . _ : - |
Your order number. Unique among the merchant's pay-ins |
amount |
string | yes | > 0, no more decimal places than the currency has | The amount |
currency |
string | yes | Uppercase currency code | ARS |
method |
string | yes | bank_transfer |
The method |
flow |
string | yes | requisite | widget |
The pay-in mode |
waitSec |
integer | no | From 0 to the platform limit (the default limit is 20); without the field — the platform default (20 by default) | Only flow: requisite: how many seconds the response waits for an executor to be assigned, counted from the start of the request. Above the limit — 400 validation_failed |
customer.id |
string | yes | 1–128 printable ASCII characters without spaces | Your client ID |
customer.name |
string | no | 2–100 characters | The client's name; repeated spaces are collapsed |
customer.email |
string | no | E-mail, up to 254 characters | The client's e-mail |
customer.ip |
string | no | IPv4 or IPv6 | The client's IP address |
returnUrls.success |
string | no | https://, up to 2048 characters, without # and without a login in the address |
Where the payment page returns the client after a successful payment |
returnUrls.fail |
string | no | Same | …after a failure |
returnUrls.back |
string | no | Same | The "back" button on the payment page |
locale |
string | no | es | en, es by default |
The payment page language |
metadata |
object | no | Up to 10 keys [A-Za-z0-9_]{1,40}, values are strings up to 256 characters |
Your data; returned in responses and webhooks |
Response
| HTTP | When | Body |
|---|---|---|
201 |
The pay-in is created, or your invoiceId is attached to an open pay-in of the same client |
Pay-in object |
202 |
flow: requisite: an executor is still being found after waitSec; status: created, requisite: null |
Pay-in object |
200 |
A repeat of the same request; the Idempotent-Replayed: true header |
Pay-in object in its current state |
With flow: requisite, the 201 response usually already contains status: awaiting_payment, requisite and expiresAt: show the client the requisite and the amount (not requestedAmount). If no executor was found within the wait time, you get 201 with status: canceled and failureReason: no_trader. After 202, the payment details arrive in the payin.assigned webhook and in GET /v1/payins/{id}.
With flow: widget, the 201 response contains paymentUrl — send the client to it.
Each issue of payment details counts towards the project limits (see Limits).
{
"id": "3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44",
"object": "payin",
"invoiceId": "inv-100501",
"invoiceIds": ["inv-100501"],
"status": "awaiting_payment",
"final": false,
"flow": "requisite",
"method": "bank_transfer",
"currency": "ARS",
"requestedAmount": "15000.00",
"amount": "15000.00",
"fee": "375.00",
"net": "14625.00",
"customer": { "id": "client-42", "name": "Juan Perez" },
"paymentUrl": null,
"requisite": {
"type": "cvu",
"number": "0000003110000987654323",
"alias": null,
"holderName": "Martin Suarez",
"holderTaxId": null,
"bankName": "Banco Ejemplo"
},
"expiresAt": "2026-11-19T16:16:53.925Z",
"failureReason": null,
"dispute": null,
"returnUrls": { "success": "https://shop.example.com/pay/ok", "fail": null, "back": null },
"locale": "en",
"metadata": { "orderId": "A-1001" },
"test": false,
"version": 2,
"createdAt": "2026-11-19T16:07:53.910Z",
"updatedAt": "2026-11-19T16:07:53.979Z",
"assignedAt": "2026-11-19T16:07:53.925Z",
"clientPaidAt": null,
"completedAt": null,
"expiredAt": null,
"canceledAt": null
}Errors
| HTTP | code |
When |
|---|---|---|
400 |
validation_failed |
A field failed validation; details.fields is the list of fields. This includes: more decimal places than the currency has; an amount not greater than zero; waitSec above the allowed value |
400 |
malformed_json |
The body is not JSON |
403 |
ip_allowlist_required |
flow: requisite with a key without an IP list |
409 |
idempotency_conflict |
This invoiceId was already used with different parameters; details.id is that pay-in |
409 |
invoice_id_taken |
This invoiceId is taken by a pay-in of another project of the merchant |
409 |
customer_open_payins_limit |
The client already has the maximum number of open pay-ins in the project; details.limit |
422 |
method_unavailable |
The method or the currency is not enabled for the project's pay-ins; details: method, currency, direction |
422 |
amount_out_of_range |
The amount is outside the method limits; details.min, details.max |
422 |
feature_unavailable |
flow: widget, but the payment page is not available; details.feature: "widget" |
429 |
requisite_reveal_limit |
The project has used up its payment details issue limit; details.limit, details.kind (see Limits) |
500 |
no_widget_domain |
flow: widget, but the project has no active payment page address; the pay-in is not created |
Plus the common authentication errors and temporary failures.
payin8 POST /v1/payins '{"invoiceId":"inv-100501","amount":"15000.00","currency":"ARS","method":"bank_transfer","flow":"requisite","customer":{"id":"client-42","name":"Juan Perez"},"metadata":{"orderId":"A-1001"}}'const { status, body } = await payin8Request('POST', '/v1/payins', {
invoiceId: 'inv-100501',
amount: '15000.00',
currency: 'ARS',
method: 'bank_transfer',
flow: 'requisite',
customer: { id: 'client-42', name: 'Juan Perez' },
metadata: { orderId: 'A-1001' },
});
if (status === 201 || status === 200) {
console.log(body.status, body.amount, body.requisite);
} else if (status === 202) {
console.log('an executor is being found, wait for the payin.assigned webhook', body.id);
} else {
console.log(status, body.code, body.details);
}status, headers, body = payin8_request("POST", "/v1/payins", {
"invoiceId": "inv-100501",
"amount": "15000.00",
"currency": "ARS",
"method": "bank_transfer",
"flow": "requisite",
"customer": {"id": "client-42", "name": "Juan Perez"},
"metadata": {"orderId": "A-1001"},
})
if status in (200, 201):
print(body["status"], body["amount"], body["requisite"])
elif status == 202:
print("an executor is being found, wait for the payin.assigned webhook", body["id"])
else:
print(status, body["code"], body.get("details"))$r = payin8_request('POST', '/v1/payins', [
'invoiceId' => 'inv-100501',
'amount' => '15000.00',
'currency' => 'ARS',
'method' => 'bank_transfer',
'flow' => 'requisite',
'customer' => ['id' => 'client-42', 'name' => 'Juan Perez'],
'metadata' => ['orderId' => 'A-1001'],
]);
if ($r['status'] === 201 || $r['status'] === 200) {
echo $r['body']['status'], ' ', $r['body']['amount'], ' ', json_encode($r['body']['requisite']), "\n";
} elseif ($r['status'] === 202) {
echo "an executor is being found, wait for the payin.assigned webhook ", $r['body']['id'], "\n";
} else {
echo $r['status'], ' ', $r['body']['code'], "\n";
}GET/v1/payins/{id}#
Returns a pay-in of the project by id. Key right: merchant_api.payins.read.
| Path parameter | Type | Meaning |
|---|---|---|
id |
string (UUID) | The pay-in id |
Response 200 — the pay-in object. The payment details are present with flow: requisite in the awaiting_payment and client_paid statuses.
Errors: 400 validation_failed — id is not a UUID; 404 not_found — the pay-in is not in the key's project.
payin8 GET /v1/payins/3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44const { status, body } = await payin8Request('GET', '/v1/payins/3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44');
console.log(status, body.status, body.final);status, headers, body = payin8_request("GET", "/v1/payins/3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44")
print(status, body.get("status"), body.get("final"))$r = payin8_request('GET', '/v1/payins/3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44');
echo $r['status'], ' ', $r['body']['status'] ?? $r['body']['code'], "\n";GET/v1/payins/by-invoice/{invoiceId}#
Returns a pay-in by your number, including a number attached to the deal. Key right: merchant_api.payins.read. Useful if the creation response was lost.
| Path parameter | Type | Meaning |
|---|---|---|
invoiceId |
string | Your number, 1–64 characters A–Z a–z 0–9 . _ : - |
Response 200 — the pay-in object; invoiceId holds the number from the request.
Errors: 400 validation_failed — the number is not in the format; 404 not_found — there is no pay-in with this number in the key's project.
payin8 GET /v1/payins/by-invoice/inv-100501const { status, body } = await payin8Request('GET', '/v1/payins/by-invoice/inv-100501');
console.log(status, body.id, body.status);status, headers, body = payin8_request("GET", "/v1/payins/by-invoice/inv-100501")
print(status, body.get("id"), body.get("status"))$r = payin8_request('GET', '/v1/payins/by-invoice/inv-100501');
echo $r['status'], ' ', $r['body']['id'] ?? $r['body']['code'], "\n";GET/v1/payins#
Lists the project's pay-ins, newest first. Key right: merchant_api.payins.read. The payment details in list items are always null.
| Query parameter | Type | Required | Meaning |
|---|---|---|---|
status |
string | no | A single pay-in status |
customerId |
string | no | The client's customer.id |
createdFrom |
string | no | Created at or after this point (ISO 8601) |
createdTo |
string | no | Created before this point (ISO 8601, the bound is excluded) |
limit |
integer | no | 1–100, 50 by default |
cursor |
string | no | The nextCursor of the previous page |
Without a period, the list covers the last 7 days. The period is at most 31 days. Details on the period and pages are in Pagination and filters.
Response 200:
| Field | Type | Meaning |
|---|---|---|
items |
object[] | Pay-in objects, newest first |
nextCursor |
string | null | The cursor of the next page; null — this is the last page |
Errors: 400 validation_failed — an unknown status, an invalid date, createdFrom not earlier than createdTo, a period longer than 31 days, limit outside 1–100, a corrupted cursor.
payin8 GET "/v1/payins?status=completed&createdFrom=2026-11-01T00:00:00Z&createdTo=2026-11-20T00:00:00Z&limit=50"// all completed pay-ins for the period, page by page
let cursor = null;
do {
const query = new URLSearchParams({ status: 'completed', createdFrom: '2026-11-01T00:00:00Z', createdTo: '2026-11-20T00:00:00Z', limit: '50' });
if (cursor) query.set('cursor', cursor);
const { status, body } = await payin8Request('GET', `/v1/payins?${query}`);
if (status !== 200) throw new Error(`${status} ${body.code}`);
for (const payin of body.items) console.log(payin.id, payin.invoiceId, payin.amount);
cursor = body.nextCursor;
} while (cursor);from urllib.parse import urlencode
cursor = None
while True:
query = {"status": "completed", "createdFrom": "2026-11-01T00:00:00Z", "createdTo": "2026-11-20T00:00:00Z", "limit": "50"}
if cursor:
query["cursor"] = cursor
status, headers, body = payin8_request("GET", "/v1/payins?" + urlencode(query))
if status != 200:
raise RuntimeError(f"{status} {body['code']}")
for payin in body["items"]:
print(payin["id"], payin["invoiceId"], payin["amount"])
cursor = body["nextCursor"]
if not cursor:
break$cursor = null;
do {
$query = ['status' => 'completed', 'createdFrom' => '2026-11-01T00:00:00Z', 'createdTo' => '2026-11-20T00:00:00Z', 'limit' => '50'];
if ($cursor !== null) {
$query['cursor'] = $cursor;
}
$r = payin8_request('GET', '/v1/payins?' . http_build_query($query));
if ($r['status'] !== 200) {
throw new RuntimeException($r['status'] . ' ' . $r['body']['code']);
}
foreach ($r['body']['items'] as $payin) {
echo $payin['id'], ' ', $payin['invoiceId'], ' ', $payin['amount'], "\n";
}
$cursor = $r['body']['nextCursor'];
} while ($cursor !== null);POST/v1/payins/{id}/cancel#
Cancels a pay-in while the client has not received the payment details. Key right: merchant_api.payins.cancel. The body is empty or {}.
You can cancel:
- a pay-in in the
createdstatus (no executor assigned yet); - a
flow: widgetpay-in in theawaiting_paymentstatus, while the client has not opened the payment details on the payment page.
A flow: requisite pay-in counts as shown at the moment an executor is assigned: the payment details have already reached you in the API response or a webhook. That is why it cannot be canceled after awaiting_payment — wait for the term to expire.
Canceling an already canceled pay-in returns 200 with its current state.
| Path parameter | Type | Meaning |
|---|---|---|
id |
string (UUID) | The pay-in id |
Response 200 — the pay-in object with status: canceled, failureReason: canceled_by_merchant. The payin.failed webhook arrives.
Errors
| HTTP | code |
When |
|---|---|---|
404 |
not_found |
The pay-in is not in the key's project |
409 |
requisite_already_shown |
The payment details have already been issued; details.shownAt — when, details.via — where: api, webhook or widget |
409 |
invalid_state |
The status does not allow cancellation; details.status is the current one |
409 |
dispute_open |
A dispute is open on the deal; details.disputeId |
payin8 POST /v1/payins/3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44/cancelconst { status, body } = await payin8Request('POST', '/v1/payins/3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44/cancel');
console.log(status, body.status ?? body.code, body.details ?? body.failureReason);status, headers, body = payin8_request("POST", "/v1/payins/3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44/cancel")
print(status, body.get("status") or body.get("code"))$r = payin8_request('POST', '/v1/payins/3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44/cancel');
echo $r['status'], ' ', $r['body']['status'] ?? $r['body']['code'], "\n";Repeat for the same client#
If the client (customer.id) already has an open pay-in in the project for the same amount (the request amount), with the same method and currency, created recently (by default, no earlier than 15 minutes ago; the window is a platform setting), Payin8 does not create a new deal. It attaches your new invoiceId to the open one: the 201 response (202 for flow: requisite while an executor is being found) contains the id of that deal, your new number in invoiceId and all numbers in invoiceIds. The client pays once; the outcome comes for a single deal. Such a pay-in does not count towards the client's open pay-ins limit.
The pay-in mode (flow) is not compared when attaching: the response describes the already open deal in its own flow. So always take from the response what it contains: requisite (if the deal is flow: requisite) or paymentUrl (if it is flow: widget), not what you expected from your request.
API
Payouts#
A payout is a transfer from your Payin8 balance to the recipient's bank account. A Payin8 executor makes the transfer and attaches a receipt. How a payout works — in the overview; statuses — in Deal statuses.
Payout object#
This is how a payout looks in API responses and in the data field of payout.* webhooks.
| Field | Type | Meaning |
|---|---|---|
id |
string (UUID) | The payout ID in Payin8 |
object |
string | Always payout |
invoiceId |
string | Your payout number |
invoiceIds |
string[] | All numbers of the deal; a payout has one |
status |
string | created, offered, in_progress, verifying, completed, canceled |
final |
boolean | true — the status will not change by itself any more (completed or canceled without an open dispute) |
method |
string | bank_transfer |
currency |
string | The currency, for example ARS |
amount |
string | The amount from the request — the recipient gets it |
feePayer |
string | Who pays the fee; currently always merchant |
fee |
string | Your payout fee at the moment; "0.00" for a canceled payout |
requestedFee |
string | The fee calculated at creation |
totalDebit |
string | The balance debit for the payout: amount + requestedFee. Held at creation; for a payout that waits for a balance top-up (created), not held yet; for a payout canceled before the hold, "0.00" |
recipientAmount |
string | How much must go to the recipient |
paidAmount |
string | null | How much was actually transferred; null while the payout is open; "0.00" for a canceled payout |
refundedAmount |
string | null | How much returned to the balance (partial execution, cancellation, cancellation of a completed payout after a dispute); null while the payout is open |
bankReference |
string | null | The bank operation number of the transfer, if the executor entered it |
recipient |
object | The recipient (see below) |
recipient.type |
string | cvu, cbu or alias |
recipient.account |
string | 22 digits, or an alias in lowercase |
recipient.holderName |
string | The account holder as you sent it (repeated spaces collapsed) |
recipient.taxId |
string | null | CUIT/CUIL, 11 digits without hyphens |
customer |
object | The client's { "id", "name" } from the request |
receipts |
object[] | The executor's receipts: id, name, contentType, size (bytes), uploadedAt. Download — GET /v1/payouts/{id}/receipts/{fileId} |
failureReason |
string | null | The reason for canceled (see Reasons) |
dispute |
object | null | { "id", "status" } of an open dispute |
metadata |
object | Your metadata |
test |
boolean | Reserved, currently always false |
version |
integer | The version number; grows with each change |
createdAt, updatedAt |
string | Created, changed |
expiresAt |
string | The time by which the payout must be taken (including the wait for funds on the balance) |
startedAt |
string | null | The executor took the payout |
completedAt |
string | null | Completed |
canceledAt |
string | null | Canceled |
For a completed or canceled payout, totalDebit − refundedAmount = paidAmount + fee always holds.
Endpoints#
POST/v1/payouts#
Creates a payout and holds amount + the fee on the balance. Key right: merchant_api.payouts.create; the key must have a non-empty IP list.
Request body
| Field | Type | Required | Constraints | Meaning |
|---|---|---|---|---|
invoiceId |
string | yes | 1–64 characters A–Z a–z 0–9 . _ : - |
Your payout number. Unique among the merchant's payouts |
amount |
string | yes | > 0, no more decimal places than the currency has | How much the recipient gets |
currency |
string | yes | Currency code | ARS |
method |
string | yes | bank_transfer |
The method |
feePayer |
string | no | merchant (default) |
Who pays the fee: currently only merchant — the fee is debited on top of the amount. The allowed values are in payout.feePayers of the GET /v1/methods response |
recipient.account |
string | yes | Up to 40 characters | A CVU or CBU — 22 digits with valid check digits (spaces, dots and hyphens are dropped), or an alias — 6–20 characters A–Z a–z 0–9 . - |
recipient.holderName |
string | yes | 2–100 characters | The account holder's name |
recipient.taxId |
string | no | Up to 13 characters | The holder's CUIT/CUIL: 11 digits with a valid check digit, hyphens allowed |
customer.id |
string | yes | 1–128 printable ASCII characters without spaces | Your ID of the client the payout is for |
customer.name |
string | no | 2–100 characters | The client's name |
metadata |
object | no | Up to 10 keys [A-Za-z0-9_]{1,40}, values are strings up to 256 characters |
Your data |
Response
| HTTP | When | Body |
|---|---|---|
201 |
The payout is created | Payout object |
200 |
A repeat of the same request; the Idempotent-Replayed: true header |
The payout object in its current state |
A new payout is usually offered right away. Check status in a 201 response too: if there are no suitable executors, the payout can already come back canceled (failureReason: no_trader or expired); the held amount is then returned to the balance (refundedAmount = totalDebit), and the payout.failed webhook arrives. If the balance does not have enough funds, the behavior depends on the "Payout without funds on the balance" project rule (see Project rules): "reject at once" — the request is rejected with 409 insufficient_balance; "wait for a top-up" — the payout is created in the created status and waits for a balance top-up until expiresAt; if the top-up does not come in time — canceled with failureReason: insufficient_balance.
{
"id": "7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f",
"object": "payout",
"invoiceId": "wd-200731",
"invoiceIds": ["wd-200731"],
"status": "offered",
"final": false,
"method": "bank_transfer",
"currency": "ARS",
"amount": "20000.00",
"feePayer": "merchant",
"fee": "200.00",
"requestedFee": "200.00",
"totalDebit": "20200.00",
"recipientAmount": "20000.00",
"paidAmount": null,
"refundedAmount": null,
"bankReference": null,
"recipient": {
"type": "cvu",
"account": "0000003110000123456781",
"holderName": "Maria Gomez",
"taxId": "20312345677"
},
"customer": { "id": "client-77", "name": "Maria Gomez" },
"receipts": [],
"failureReason": null,
"dispute": null,
"metadata": { "withdrawalId": "W-77" },
"test": false,
"version": 1,
"createdAt": "2026-11-19T16:09:23.307Z",
"updatedAt": "2026-11-19T16:09:23.334Z",
"expiresAt": "2026-11-19T20:09:23.292Z",
"startedAt": null,
"completedAt": null,
"canceledAt": null
}Errors
| HTTP | code |
When |
|---|---|---|
400 |
validation_failed |
A field failed validation; details.fields |
400 |
malformed_json |
The body is not JSON |
403 |
ip_allowlist_required |
The key has no IP list |
409 |
idempotency_conflict |
This invoiceId is already used with different parameters; details.id is that payout |
409 |
invoice_id_taken |
This invoiceId is taken by a payout of another project of the merchant |
409 |
insufficient_balance |
The available balance is not enough; details.currency, details.available, details.required |
422 |
invalid_recipient |
The recipient's account or CUIT is invalid; details.field (recipient.account, recipient.holderName, recipient.taxId), details.rule: format — wrong format, checksum — the check digit does not match |
422 |
fee_payer_unavailable |
feePayer is not allowed; details.allowed lists the allowed values |
422 |
method_unavailable |
Payouts for the method or the currency are not enabled for the project; details: method, currency, direction |
422 |
amount_out_of_range |
The amount is outside the method limits; details.min, details.max |
422 |
negative_margin |
The payout cannot be made with the current tariff terms; contact support |
Plus the common authentication errors and temporary failures.
payin8 POST /v1/payouts '{"invoiceId":"wd-200731","amount":"20000.00","currency":"ARS","method":"bank_transfer","recipient":{"account":"0000003110000123456781","holderName":"Maria Gomez","taxId":"20-31234567-7"},"customer":{"id":"client-77","name":"Maria Gomez"},"metadata":{"withdrawalId":"W-77"}}'const { status, body } = await payin8Request('POST', '/v1/payouts', {
invoiceId: 'wd-200731',
amount: '20000.00',
currency: 'ARS',
method: 'bank_transfer',
recipient: { account: '0000003110000123456781', holderName: 'Maria Gomez', taxId: '20-31234567-7' },
customer: { id: 'client-77', name: 'Maria Gomez' },
metadata: { withdrawalId: 'W-77' },
});
if (status === 201 || status === 200) {
console.log(body.id, body.status, body.totalDebit);
} else {
console.log(status, body.code, body.details);
}status, headers, body = payin8_request("POST", "/v1/payouts", {
"invoiceId": "wd-200731",
"amount": "20000.00",
"currency": "ARS",
"method": "bank_transfer",
"recipient": {"account": "0000003110000123456781", "holderName": "Maria Gomez", "taxId": "20-31234567-7"},
"customer": {"id": "client-77", "name": "Maria Gomez"},
"metadata": {"withdrawalId": "W-77"},
})
if status in (200, 201):
print(body["id"], body["status"], body["totalDebit"])
else:
print(status, body["code"], body.get("details"))$r = payin8_request('POST', '/v1/payouts', [
'invoiceId' => 'wd-200731',
'amount' => '20000.00',
'currency' => 'ARS',
'method' => 'bank_transfer',
'recipient' => ['account' => '0000003110000123456781', 'holderName' => 'Maria Gomez', 'taxId' => '20-31234567-7'],
'customer' => ['id' => 'client-77', 'name' => 'Maria Gomez'],
'metadata' => ['withdrawalId' => 'W-77'],
]);
if ($r['status'] === 201 || $r['status'] === 200) {
echo $r['body']['id'], ' ', $r['body']['status'], ' ', $r['body']['totalDebit'], "\n";
} else {
echo $r['status'], ' ', $r['body']['code'], ' ', json_encode($r['body']['details'] ?? null), "\n";
}GET/v1/payouts/{id}#
Returns a payout of the project by id. Key right: merchant_api.payouts.read.
| Path parameter | Type | Meaning |
|---|---|---|
id |
string (UUID) | The payout id |
Response 200 — payout object.
Errors: 400 validation_failed — id is not a UUID; 404 not_found — the payout is not in the key's project.
payin8 GET /v1/payouts/7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6fconst { status, body } = await payin8Request('GET', '/v1/payouts/7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f');
console.log(status, body.status, body.paidAmount, body.receipts);status, headers, body = payin8_request("GET", "/v1/payouts/7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f")
print(status, body.get("status"), body.get("paidAmount"), body.get("receipts"))$r = payin8_request('GET', '/v1/payouts/7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f');
echo $r['status'], ' ', $r['body']['status'] ?? $r['body']['code'], "\n";GET/v1/payouts/by-invoice/{invoiceId}#
Returns a payout by your number. Key right: merchant_api.payouts.read.
| Path parameter | Type | Meaning |
|---|---|---|
invoiceId |
string | Your number, 1–64 characters A–Z a–z 0–9 . _ : - |
Response 200 — payout object.
Errors: 400 validation_failed — the number is not in the format; 404 not_found — there is no payout with this number in the key's project.
payin8 GET /v1/payouts/by-invoice/wd-200731const { status, body } = await payin8Request('GET', '/v1/payouts/by-invoice/wd-200731');
console.log(status, body.id, body.status);status, headers, body = payin8_request("GET", "/v1/payouts/by-invoice/wd-200731")
print(status, body.get("id"), body.get("status"))$r = payin8_request('GET', '/v1/payouts/by-invoice/wd-200731');
echo $r['status'], ' ', $r['body']['id'] ?? $r['body']['code'], "\n";GET/v1/payouts#
Lists the project's payouts, newest first. Key right: merchant_api.payouts.read.
| Query parameter | Type | Required | Meaning |
|---|---|---|---|
status |
string | no | One payout status |
customerId |
string | no | The client's customer.id |
createdFrom |
string | no | Created at or after this time (ISO 8601) |
createdTo |
string | no | Created before this time (ISO 8601, the bound is excluded) |
limit |
integer | no | 1–100, 50 by default |
cursor |
string | no | nextCursor of the previous page |
Without a period — the last 7 days; the period is at most 31 days (see Pagination and filters).
Response 200: items — payout objects, nextCursor — the cursor of the next page or null.
Errors: 400 validation_failed — as for the pay-in list.
payin8 GET "/v1/payouts?customerId=client-77&limit=20"const { status, body } = await payin8Request('GET', '/v1/payouts?customerId=client-77&limit=20');
for (const payout of body.items) console.log(payout.id, payout.status, payout.amount);
console.log('next page:', body.nextCursor);status, headers, body = payin8_request("GET", "/v1/payouts?customerId=client-77&limit=20")
for payout in body["items"]:
print(payout["id"], payout["status"], payout["amount"])
print("next page:", body["nextCursor"])$r = payin8_request('GET', '/v1/payouts?customerId=client-77&limit=20');
foreach ($r['body']['items'] as $payout) {
echo $payout['id'], ' ', $payout['status'], ' ', $payout['amount'], "\n";
}
echo 'next page: ', $r['body']['nextCursor'] ?? 'null', "\n";GET/v1/payouts/{id}/receipts/{fileId}#
Downloads an executor's receipt for a payout. fileId is an id from the payout's receipts array. Key right: merchant_api.payouts.read.
| Path parameter | Type | Meaning |
|---|---|---|
id |
string (UUID) | The payout id |
fileId |
string (UUID) | The receipt id |
Response 200 — the file bytes (not JSON). Headers:
| Header | Value |
|---|---|
Content-Type |
application/pdf, image/png, image/jpeg or image/webp |
Content-Length |
The size in bytes |
Content-Disposition |
attachment; filename="…"; filename*=UTF-8''… |
ETag |
The SHA-256 of the file in quotes. A request with If-None-Match set to this value gets 304 without a body |
Errors: 400 validation_failed — id or fileId is not a UUID; 404 not_found — there is no such payout in the project or no such receipt on this payout.
payin8 GET /v1/payouts/7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f/receipts/5d2e8f1a-9c3b-4a7d-b6e5-0f1e2d3c4b5a > receipt.binimport { writeFile } from 'node:fs/promises';
const { status, headers, body } = await payin8Request(
'GET',
'/v1/payouts/7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f/receipts/5d2e8f1a-9c3b-4a7d-b6e5-0f1e2d3c4b5a',
);
if (status === 200) {
await writeFile('receipt.bin', body);
console.log(headers['content-type'], body.length);
} else {
console.log(status, body.code);
}status, headers, body = payin8_request(
"GET", "/v1/payouts/7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f/receipts/5d2e8f1a-9c3b-4a7d-b6e5-0f1e2d3c4b5a"
)
if status == 200:
with open("receipt.bin", "wb") as f:
f.write(body)
print(headers["Content-Type"], len(body))
else:
print(status, body["code"])$r = payin8_request('GET', '/v1/payouts/7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f/receipts/5d2e8f1a-9c3b-4a7d-b6e5-0f1e2d3c4b5a');
if ($r['status'] === 200) {
file_put_contents('receipt.bin', $r['body']);
echo $r['headers']['content-type'], ' ', strlen($r['body']), "\n";
} else {
echo $r['status'], ' ', $r['body']['code'], "\n";
}POST/v1/payouts/{id}/cancel#
Cancels a payout before an executor takes it: in the created and offered statuses. The held amount returns to the balance. Key right: merchant_api.payouts.cancel. The body is empty or {}.
Canceling a payout that is already canceled returns 200 with its current state.
| Path parameter | Type | Meaning |
|---|---|---|
id |
string (UUID) | The payout id |
Response 200 — the payout object with status: canceled, failureReason: canceled_by_merchant, refundedAmount = totalDebit. The payout.failed webhook arrives.
Errors
| HTTP | code |
When |
|---|---|---|
404 |
not_found |
The payout is not in the key's project |
409 |
invalid_state |
An executor has already taken the payout, or it is finished; details.status is the current status |
409 |
dispute_open |
The payout has an open dispute; details.disputeId |
payin8 POST /v1/payouts/7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f/cancelconst { status, body } = await payin8Request('POST', '/v1/payouts/7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f/cancel');
console.log(status, body.status ?? body.code, body.refundedAmount ?? body.details);status, headers, body = payin8_request("POST", "/v1/payouts/7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f/cancel")
print(status, body.get("status") or body.get("code"))$r = payin8_request('POST', '/v1/payouts/7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f/cancel');
echo $r['status'], ' ', $r['body']['status'] ?? $r['body']['code'], "\n";API
Balance and methods#
The merchant balance and the project's method terms: amount limits and fees. How the balance is topped up and how to withdraw money is in the cabinet sections Balance and Withdrawals.
Endpoints#
GET/v1/balance#
The merchant balance by currency. Key right: merchant_api.balance.read. The balance is shared by all of the merchant's projects: keys of different projects see the same amounts.
Response 200
| Field | Type | Meaning |
|---|---|---|
balances |
object[] | The merchant's accounts, one per currency |
balances[].currency |
string | The currency |
balances[].available |
string | Available: can be spent on payouts and withdrawals |
balances[].hold |
string | Held for open operations (for example, created payouts) |
balances[].total |
string | available + hold |
{
"balances": [
{ "currency": "ARS", "available": "1243903.76", "hold": "20200.00", "total": "1264103.76" }
]
}A pay-in is credited to available with its net amount after completed. When a payout is created, totalDebit moves from available to hold; after the payout is executed, the held amount is debited, and after it is canceled, the amount returns to available. In the cabinet, these parts of the balance are called "Available", "Frozen" and "Total" (see Balance).
payin8 GET /v1/balanceconst { status, body } = await payin8Request('GET', '/v1/balance');
for (const b of body.balances) console.log(b.currency, b.available, b.hold, b.total);status, headers, body = payin8_request("GET", "/v1/balance")
for b in body["balances"]:
print(b["currency"], b["available"], b["hold"], b["total"])$r = payin8_request('GET', '/v1/balance');
foreach ($r['body']['balances'] as $b) {
echo $b['currency'], ' ', $b['available'], ' ', $b['hold'], ' ', $b['total'], "\n";
}GET/v1/methods#
The project's methods and currencies: the amount limits of a single deal and your fees, separately for pay-ins and payouts. Key right: merchant_api.methods.read.
Response 200
| Field | Type | Meaning |
|---|---|---|
items |
object[] | One item per "method — currency" pair |
items[].method |
string | bank_transfer |
items[].currency |
string | The currency |
items[].payin |
object | null | Pay-in terms; null — pay-ins for this pair are not available to the project |
items[].payout |
object | null | Payout terms; null — payouts are not available |
….minAmount, ….maxAmount |
string | The amount limits of a single deal; an amount outside them gets 422 amount_out_of_range |
….fee.percent |
string | The fee percentage: "2.5" means 2.5% |
….fee.min |
string | null | The minimum fee; null — none |
….fee.fixed |
string | null | A fixed amount added to the fee; null — none |
items[].payout.feePayers |
string[] | The allowed feePayer values when a payout is created |
The deal fee = the greater of (amount × percent / 100) and min, plus fixed. For a pay-in, it is calculated from the pay-in amount (fee in the pay-in object); for a payout, from the payout amount, and it is added on top (fee in the payout object).
{
"items": [
{
"method": "bank_transfer",
"currency": "ARS",
"payin": {
"minAmount": "1000.00",
"maxAmount": "1000000.00",
"fee": { "percent": "2.5", "min": null, "fixed": null }
},
"payout": {
"minAmount": "1000.00",
"maxAmount": "1000000.00",
"fee": { "percent": "1", "min": null, "fixed": null },
"feePayers": ["merchant"]
}
}
]
}payin8 GET /v1/methodsconst { status, body } = await payin8Request('GET', '/v1/methods');
for (const m of body.items) {
console.log(m.method, m.currency, 'payin:', m.payin?.fee.percent ?? 'off', 'payout:', m.payout?.fee.percent ?? 'off');
}status, headers, body = payin8_request("GET", "/v1/methods")
for m in body["items"]:
payin = m["payin"]["fee"]["percent"] if m["payin"] else "off"
payout = m["payout"]["fee"]["percent"] if m["payout"] else "off"
print(m["method"], m["currency"], "payin:", payin, "payout:", payout)$r = payin8_request('GET', '/v1/methods');
foreach ($r['body']['items'] as $m) {
echo $m['method'], ' ', $m['currency'],
' payin: ', $m['payin']['fee']['percent'] ?? 'off',
' payout: ', $m['payout']['fee']['percent'] ?? 'off', "\n";
}API
Files#
Files for the deals of your project: the client's payment receipt for a pay-in and evidence for a dispute. Executor receipts for payouts are downloaded with GET /v1/payouts/{id}/receipts/{fileId}.
Endpoints#
POST/v1/files#
Uploads a file and attaches it to a deal. Key right: merchant_api.files.create.
Query parameters
| Parameter | Type | Required | Constraints | Meaning |
|---|---|---|---|---|
dealId |
string | yes | UUID | The id of a pay-in or a payout of your project |
purpose |
string | no | receipt (default) | evidence |
receipt — the client's payment receipt for a pay-in; evidence — evidence for a dispute |
name |
string | no | 1–120 characters, without /, \ and control characters |
The file name. Without it — the name of the form part, or file |
Request body — one of the two:
- the file bytes themselves, with
Content-Typeset to the file type (for example,application/pdf); - a
multipart/form-dataform with the file in thefilepart.
The whole body is signed, as for any request (see Canonical string).
File
- Types: PDF, PNG, JPEG, WebP. The type is detected from the first bytes of the file; the
Content-Typeheader and the extension in the name do not affect it. Another type or an empty file gets415 file_type_not_allowed. - The size of one file is up to the platform limit (10 MB by default); a larger file gets
413 file_too_large.details.maxBytesis the limit that was hit, in bytes: the file limit or, if the whole request body is too large, the body limit (it is larger, with a margin for amultipartform). - A deal can have at most 10 of your files (the default value; files with any
purposecount) — otherwise409 files_limit_reached. There is also a limit on the total size of a deal's files (30 MB by default) and a daily upload limit for the merchant (2 GB by default) —413 files_quota_exceeded. - The name is cleaned: unsafe characters are replaced with spaces, and the extension is set from the actual file type (
scan.pnguploaded as a PDF becomesscan.pdf). - Uploading the same bytes with the same
purposeto the same deal again does not create a new file: the response is200with the file uploaded earlier.
Response
| HTTP | When |
|---|---|
201 |
The file is uploaded |
200 |
The deal already has this file; it is returned |
| Field | Type | Meaning |
|---|---|---|
id |
string (UUID) | The file id; for a dispute, pass it in fileIds |
name |
string | The name after cleaning |
contentType |
string | The detected type: application/pdf, image/png, image/jpeg, image/webp |
size |
integer | The size in bytes |
uploadedAt |
string | When it was uploaded |
{
"id": "9e1d2c3b-4a5f-4e6d-8c7b-6a5f4e3d2c1b",
"name": "bank-statement.pdf",
"contentType": "application/pdf",
"size": 48213,
"uploadedAt": "2026-11-19T16:10:12.480Z"
}Errors
| HTTP | code |
When |
|---|---|---|
400 |
validation_failed |
dealId is not a UUID, an invalid purpose or name, the form has no file part |
404 |
not_found |
The deal is not in the key's project |
409 |
files_limit_reached |
The deal already has the maximum number of your files; details.limit |
413 |
file_too_large |
The file is larger than the limit; details.maxBytes |
413 |
files_quota_exceeded |
A size limit is used up; details.quota (deal — the deal, merchant_day — the day), details.limitBytes |
415 |
file_type_not_allowed |
The type is not PDF, PNG, JPEG or WebP; details.allowed |
503 |
files_storage_unavailable |
Uploads are temporarily suspended; retry later |
payin8_file POST "/v1/files?dealId=3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44&purpose=evidence&name=bank-statement.pdf" ./bank-statement.pdf application/pdfimport { readFile } from 'node:fs/promises';
const pdf = await readFile('./bank-statement.pdf');
const { status, body } = await payin8Request(
'POST',
'/v1/files?dealId=3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44&purpose=evidence&name=bank-statement.pdf',
pdf,
'application/pdf',
);
console.log(status, body.id ?? body.code, body.contentType ?? body.details);with open("bank-statement.pdf", "rb") as f:
pdf = f.read()
status, headers, body = payin8_request(
"POST",
"/v1/files?dealId=3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44&purpose=evidence&name=bank-statement.pdf",
pdf,
"application/pdf",
)
print(status, body.get("id") or body.get("code"))$pdf = file_get_contents('bank-statement.pdf');
$r = payin8_request(
'POST',
'/v1/files?dealId=3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44&purpose=evidence&name=bank-statement.pdf',
$pdf,
'application/pdf'
);
echo $r['status'], ' ', $r['body']['id'] ?? $r['body']['code'], "\n";API
Disputes#
A dispute is a request to Payin8 about a deal of your project: the client paid but the pay-in is not credited; the client paid a different amount; the recipient did not get the payout. You can also open a dispute on behalf of the client. Payin8 decides on the dispute; the result arrives with the dispute.closed webhook and is visible in GET /v1/disputes/{id}. Working with disputes in the cabinet — Disputes.
While a deal has an open dispute, it has final: false, the dispute field contains { "id", "status": "open" }, and canceling the deal returns 409 dispute_open.
Dispute object#
This is how a dispute looks in API responses and in the data field of the dispute.opened and dispute.closed webhooks.
| Field | Type | Meaning |
|---|---|---|
id |
string (UUID) | The dispute ID |
object |
string | Always dispute |
dealId |
string (UUID) | The deal of the dispute |
dealType |
string | payin or payout |
invoiceId |
string | Your deal number (the first one) |
status |
string | open or closed |
reason |
string | The reason you opened the dispute with; opened_by_platform — the dispute was not opened by you (Payin8 opened it after its own check) |
comment |
string | null | Your comment at opening. Always null in webhooks — read it through the API |
claimedAmount |
string | null | The amount that, as you state, the client paid (for amount_mismatch) |
outcome |
string | null | The outcome of a closed dispute (see below); null for an open one |
resolvedAmount |
string | null | The final deal amount with outcome: amount_changed |
files |
object[] | Your evidence files for the deal: id, name, contentType, size, uploadedAt |
openedAt |
string | Opened |
closedAt |
string | null | Closed |
Dispute outcomes (outcome)
| Value | What happened to the deal |
|---|---|
deal_completed |
The deal is confirmed (the pay-in is credited, the payout is recognized as completed) |
amount_changed |
The deal amount is changed to resolvedAmount; for a pay-in, the payin.amount_changed webhook arrives |
deal_canceled |
The deal is canceled |
deal_reversed |
The completed deal is canceled and the money is returned (failureReason: reversed_after_dispute) |
rejected |
The deal stays as it was |
Endpoints#
POST/v1/disputes#
Opens a dispute on a deal of the project. Key right: merchant_api.disputes.create.
Request body
| Field | Type | Required | Constraints | Meaning |
|---|---|---|---|---|
dealId |
string | yes | UUID | The id of the pay-in or the payout |
reason |
string | yes | see the table below | The reason |
comment |
string | no | Up to 2000 characters | A description for Payin8 |
claimedAmount |
string | for amount_mismatch |
> 0, no more decimal places than the currency has | How much the client paid |
fileIds |
string[] | no | Up to 10 distinct UUIDs | Your files of this deal, uploaded with POST /v1/files. The dispute's files field shows only files with purpose=evidence, so upload evidence with it |
| Deal | reason |
When |
|---|---|---|
| Pay-in | payment_not_credited |
The client paid, but the pay-in is not completed |
| Pay-in | amount_mismatch |
The client paid a different amount; claimedAmount is required |
| Pay-in, payout | other |
Something else |
| Payout | recipient_not_paid |
The recipient did not get the money |
When you can open one
- A pay-in — in the
awaiting_payment,client_paid,expired,completedstatuses, and alsocanceledif an executor was assigned. - A payout — in the
in_progressandcompletedstatuses. - No later than the set term after the deal was created (7 days by default); the term is in
details.untilof thewindowrejection.
If the deal already has an open dispute, a new one is not created: the response is 200 with the open dispute, and your comment and files are added to it. The dispute's reason and comment fields do not change.
Response
| HTTP | When |
|---|---|
201 |
The dispute is opened; the dispute.opened webhook arrives |
200 |
The deal already had an open dispute; it is returned |
The body is the dispute object:
{
"id": "c2a1b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"object": "dispute",
"dealId": "3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44",
"dealType": "payin",
"invoiceId": "inv-100501",
"status": "open",
"reason": "amount_mismatch",
"comment": "The client paid 11000.00, see the bank statement",
"claimedAmount": "11000.00",
"outcome": null,
"resolvedAmount": null,
"files": [
{
"id": "9e1d2c3b-4a5f-4e6d-8c7b-6a5f4e3d2c1b",
"name": "bank-statement.pdf",
"contentType": "application/pdf",
"size": 48213,
"uploadedAt": "2026-11-19T16:10:12.480Z"
}
],
"openedAt": "2026-11-19T16:10:18.841Z",
"closedAt": null
}Errors
| HTTP | code |
When |
|---|---|---|
400 |
validation_failed |
A field failed validation, including a missing claimedAmount with amount_mismatch |
404 |
not_found |
The deal is not in the key's project |
409 |
dispute_not_allowed |
A dispute cannot be opened now; details.why: reason — the reason does not fit the deal type, status — the deal status (in details.status), window — the term has passed (in details.until) |
422 |
file_not_attachable |
A file from fileIds cannot be attached; details.fileId and details.why: deal — the file belongs to another deal, uploader — the file was not uploaded by you, status — the file does not exist or is no longer available |
payin8 POST /v1/disputes '{"dealId":"3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44","reason":"amount_mismatch","claimedAmount":"11000.00","comment":"The client paid 11000.00, see the bank statement","fileIds":["9e1d2c3b-4a5f-4e6d-8c7b-6a5f4e3d2c1b"]}'const { status, body } = await payin8Request('POST', '/v1/disputes', {
dealId: '3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44',
reason: 'amount_mismatch',
claimedAmount: '11000.00',
comment: 'The client paid 11000.00, see the bank statement',
fileIds: ['9e1d2c3b-4a5f-4e6d-8c7b-6a5f4e3d2c1b'],
});
console.log(status, body.id ?? body.code, body.status ?? body.details);status, headers, body = payin8_request("POST", "/v1/disputes", {
"dealId": "3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44",
"reason": "amount_mismatch",
"claimedAmount": "11000.00",
"comment": "The client paid 11000.00, see the bank statement",
"fileIds": ["9e1d2c3b-4a5f-4e6d-8c7b-6a5f4e3d2c1b"],
})
print(status, body.get("id") or body.get("code"), body.get("status") or body.get("details"))$r = payin8_request('POST', '/v1/disputes', [
'dealId' => '3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44',
'reason' => 'amount_mismatch',
'claimedAmount' => '11000.00',
'comment' => 'The client paid 11000.00, see the bank statement',
'fileIds' => ['9e1d2c3b-4a5f-4e6d-8c7b-6a5f4e3d2c1b'],
]);
echo $r['status'], ' ', $r['body']['id'] ?? $r['body']['code'], "\n";GET/v1/disputes/{id}#
Returns a dispute of the project. Key right: merchant_api.disputes.read.
| Path parameter | Type | Meaning |
|---|---|---|
id |
string (UUID) | The dispute id |
Response 200 — dispute object.
Errors: 400 validation_failed — id is not a UUID; 404 not_found — the dispute is not in the key's project.
payin8 GET /v1/disputes/c2a1b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5dconst { status, body } = await payin8Request('GET', '/v1/disputes/c2a1b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d');
console.log(status, body.status, body.outcome, body.resolvedAmount);status, headers, body = payin8_request("GET", "/v1/disputes/c2a1b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d")
print(status, body.get("status"), body.get("outcome"), body.get("resolvedAmount"))$r = payin8_request('GET', '/v1/disputes/c2a1b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d');
echo $r['status'], ' ', $r['body']['status'] ?? $r['body']['code'], "\n";GET/v1/disputes#
Lists the project's disputes, most recently opened first. Key right: merchant_api.disputes.read.
| Query parameter | Type | Required | Meaning |
|---|---|---|---|
status |
string | no | open or closed |
dealId |
string | no | Disputes of one deal (UUID) |
limit |
integer | no | 1–100, 50 by default |
cursor |
string | no | nextCursor of the previous page |
Response 200: items — dispute objects, nextCursor — the cursor of the next page or null.
Errors: 400 validation_failed — an invalid status, dealId, limit or cursor.
payin8 GET "/v1/disputes?status=open&limit=20"const { status, body } = await payin8Request('GET', '/v1/disputes?status=open&limit=20');
for (const d of body.items) console.log(d.id, d.dealType, d.dealId, d.reason, d.openedAt);status, headers, body = payin8_request("GET", "/v1/disputes?status=open&limit=20")
for d in body["items"]:
print(d["id"], d["dealType"], d["dealId"], d["reason"], d["openedAt"])$r = payin8_request('GET', '/v1/disputes?status=open&limit=20');
foreach ($r['body']['items'] as $d) {
echo $d['id'], ' ', $d['dealType'], ' ', $d['dealId'], ' ', $d['reason'], ' ', $d['openedAt'], "\n";
}POST/v1/disputes/{id}/evidence#
Adds a comment and/or files to an open dispute. Key right: merchant_api.disputes.create.
| Path parameter | Type | Meaning |
|---|---|---|
id |
string (UUID) | The dispute id |
Request body — at least one of the fields is required:
| Field | Type | Constraints | Meaning |
|---|---|---|---|
comment |
string | Up to 2000 characters | Text for Payin8 |
fileIds |
string[] | Up to 10 distinct UUIDs | Your files of this deal, uploaded with POST /v1/files (evidence — with purpose=evidence) |
Response 200 — dispute object. The added comment is not shown in the object: the comment field holds only the text given at opening.
Errors
| HTTP | code |
When |
|---|---|---|
400 |
validation_failed |
Neither comment nor fileIds is sent, or a field failed validation |
404 |
not_found |
The dispute is not in the key's project |
409 |
invalid_state |
The dispute is already closed; details.status: "closed" |
422 |
file_not_attachable |
A file cannot be attached; details.fileId, details.why (deal, uploader, status — as when opening a dispute) |
payin8 POST /v1/disputes/c2a1b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/evidence '{"comment":"Second page of the statement","fileIds":["9e1d2c3b-4a5f-4e6d-8c7b-6a5f4e3d2c1b"]}'const { status, body } = await payin8Request('POST', '/v1/disputes/c2a1b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/evidence', {
comment: 'Second page of the statement',
fileIds: ['9e1d2c3b-4a5f-4e6d-8c7b-6a5f4e3d2c1b'],
});
console.log(status, body.status ?? body.code, body.files?.length ?? body.details);status, headers, body = payin8_request("POST", "/v1/disputes/c2a1b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/evidence", {
"comment": "Second page of the statement",
"fileIds": ["9e1d2c3b-4a5f-4e6d-8c7b-6a5f4e3d2c1b"],
})
print(status, body.get("status") or body.get("code"))$r = payin8_request('POST', '/v1/disputes/c2a1b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/evidence', [
'comment' => 'Second page of the statement',
'fileIds' => ['9e1d2c3b-4a5f-4e6d-8c7b-6a5f4e3d2c1b'],
]);
echo $r['status'], ' ', $r['body']['status'] ?? $r['body']['code'], "\n";API
Deal statuses#
The deal status is the status field of the pay-in object and the payout object. Status changes your system needs to know about come as webhooks; you can read the status with GET at any time.
Use two fields together:
status— where the deal is now;final— whether the status can still change without your action. Whilefinal: false, do not treat the outcome as final: an expired pay-in can still be completed, and a dispute can be in progress on the deal.
Pay-in statuses#
| Status | Meaning | final |
|---|---|---|
created |
The pay-in is created; Payin8 is looking for an executor and payment details | false |
awaiting_payment |
Payment details are assigned; waiting for the client's transfer until expiresAt |
false |
client_paid |
The client marked on the payment page that they sent the money; the receipt of funds is not confirmed yet. Only with flow: widget |
false |
completed |
The receipt of funds is confirmed, net is credited to the balance |
true if there is no open dispute |
expired |
The payment term passed without confirmation, or the client canceled the payment on the payment page | false while the late confirmation window is open; then true |
canceled |
The pay-in is canceled: no executor was found, you, the client or Payin8 canceled it, or a completed pay-in was canceled by a dispute | true if there is no open dispute |
Pay-in transitions#
| From | To | When | Webhook |
|---|---|---|---|
created |
awaiting_payment |
An executor is assigned | payin.assigned |
created |
canceled |
No executor found (no_trader); canceled by you, the client or Payin8 |
payin.failed |
awaiting_payment |
client_paid |
The client marked the payment on the payment page | — |
awaiting_payment, client_paid |
completed |
The receipt of funds is confirmed | payin.completed |
awaiting_payment, client_paid |
expired |
The expiresAt term passed; the client canceled the payment on the payment page (from awaiting_payment) |
payin.failed |
awaiting_payment, client_paid |
canceled |
Canceled by you (only flow: widget before the payment details are shown) or by Payin8 |
payin.failed |
expired |
completed |
The money came after the term; the receipt of funds is confirmed within the late confirmation window | payin.completed |
expired, canceled |
completed / canceled |
Payin8 decision on a dispute | payin.completed / payin.failed |
completed |
canceled |
Dispute decision: the completed pay-in is canceled (reversed_after_dispute), the credit is debited from the balance |
payin.failed |
completed |
completed |
Dispute decision: the pay-in amount is changed | payin.amount_changed |
The confirmed amount can differ from the amount to pay: if the client transferred a different amount, the pay-in can be completed for the actual amount. The final amount, fee and net are in the payin.completed webhook and in GET /v1/payins/{id}.
Pay-in timing#
- Executor search starts right after creation and lasts no longer than the configured time (30 seconds by default). If no executor is found, the pay-in is
canceledwithfailureReason: no_trader. - The payment term starts when an executor is assigned; it ends at
expiresAt. The duration is set in the settings (15 minutes by default). - Late confirmation window. After
expired, the pay-in can still becomecompletedif the money does come. The window starts atexpiresAt; while it is open, an expired pay-in hasfinal: false. Whether the window is on and how long it lasts are project settings (on by default, 24 hours; see Projects).
Pay-in failure reasons#
The failureReason field is set in the expired and canceled statuses; in the others it is null.
failureReason |
Status | What happened |
|---|---|---|
expired |
expired |
The payment term passed |
canceled_by_customer |
expired or canceled |
The client canceled the payment on the payment page: before assignment — canceled, after — expired with a late confirmation window |
no_trader |
canceled |
No executor was found |
canceled_by_merchant |
canceled |
You canceled it (POST /v1/payins/{id}/cancel or the cabinet) |
canceled_by_support |
canceled |
Payin8 canceled it (including by a dispute decision) |
reversed_after_dispute |
canceled |
A completed pay-in was canceled by a dispute decision |
Payout statuses#
| Status | Meaning | final |
|---|---|---|
created |
The payout is waiting for a balance deposit: there was not enough money at creation, and the project is set to wait | false |
offered |
The amount is held; the payout is offered to executors | false |
in_progress |
An executor took the payout and is transferring the money | false |
verifying |
Reserved; payouts do not move to this status now | false |
completed |
The transfer is done; the executor's receipts are in receipts |
true if there is no open dispute |
canceled |
The payout is canceled; the held amount returned to the balance | true if there is no open dispute |
Payout transitions#
| From | To | When | Webhook |
|---|---|---|---|
created |
offered |
The balance is topped up; the amount is held | — |
created |
canceled |
The money did not appear before expiresAt (insufficient_balance); canceled by you or Payin8 |
payout.failed |
offered |
in_progress |
An executor took the payout | — |
offered |
canceled |
Nobody took it before expiresAt (expired); no suitable executors (no_trader); canceled by you or Payin8 |
payout.failed |
in_progress |
offered |
The executor returned the payout or did not start the transfer in time; it is offered to executors again | — |
in_progress |
completed |
The transfer is done | payout.completed |
in_progress |
canceled |
The transfer is impossible: the account does not exist, the holder name did not match, the recipient's bank rejected it; or canceled by Payin8 | payout.failed |
completed |
canceled |
Dispute decision: the payout is found not executed (reversed_after_dispute) |
payout.failed |
completed |
completed |
Dispute decision: the executed amount is changed | payout.completed |
canceled |
completed |
Dispute decision: the payout is found executed | payout.completed |
A payout can be executed partially: then paidAmount is less than amount, the fee is recalculated, and the unused part of the hold returns to the balance (refundedAmount). For a completed or canceled payout, totalDebit − refundedAmount = paidAmount + fee always holds.
Payout timing#
expiresAt— the moment by which an executor must take the payout; the time spent waiting for a balance top-up is part of this term. The duration is set in the project settings (4 hours from creation by default).- A taken payout (
in_progress) is not canceled atexpiresAt. If the executor does not attach a receipt for a long time, Payin8 opens a dispute on the payout itself — it comes as thedispute.openedwebhook withreason: opened_by_platform.
Payout failure reasons#
The failureReason field is set only in the canceled status.
failureReason |
What happened |
|---|---|
expired |
Nobody took the payout before expiresAt |
insufficient_balance |
The payout was waiting for a balance top-up, and the money did not appear before expiresAt |
no_trader |
There are no executors who can execute it |
canceled_by_merchant |
You canceled it |
canceled_by_support |
Payin8 canceled it |
recipient_invalid |
The recipient's account does not exist or is closed, or the holder name did not match |
recipient_rejected |
The recipient's bank did not accept the transfer |
reversed_after_dispute |
An executed payout was canceled by a dispute decision |
Final outcome#
Treat a deal as closed when the webhook data or the GET response has final: true (a webhook arriving, for example payin.failed for an expired pay-in, does not by itself mean this):
- pay-in:
completedorcanceledwithout a dispute;expired— after the late confirmation window closes; - payout:
completedorcanceledwithout a dispute.
final: true means the deal will not change by itself. Only a dispute decision can change it — on a dispute opened by you or by Payin8: first dispute.opened comes, then, if the decision changes the deal, the deal webhook with its new state (for example, payin.failed with reversed_after_dispute or payin.amount_changed) and dispute.closed. So keep handling these webhooks after the deal has become final.
There is no webhook for final becoming true (the late confirmation window closed, a dispute closed without changing the deal): after dispute.closed, and for expired pay-ins, read the deal again with GET when it matters for your accounting.
API
Webhooks#
A webhook is a POST request from Payin8 to your server's address when something happens to a deal or a dispute. The address, the list of events and the signing secret are set for the project in the cabinet (see Webhooks); the delivery log and event resending are there too.
Address requirements#
https://only; the port is one of those allowed by Payin8 (443 or 8443 by default).- The address has a domain name (not an IP address), no user name or password, no
#; at most 2048 characters. - The name must point to public addresses: internal and reserved addresses are not accepted.
- The certificate is valid and issued by a public certificate authority; TLS 1.2 or newer.
- Redirects (3xx) are not followed and count as a failed attempt.
Events#
| Type | When | data |
|---|---|---|
payin.assigned |
An executor is assigned to the pay-in, status awaiting_payment. With flow: requisite, the body contains the payment details |
Pay-in object |
payin.completed |
The pay-in is completed: from awaiting_payment, client_paid, after the term expired, or by a dispute decision |
Pay-in object |
payin.failed |
The pay-in is expired or canceled (see failureReason) |
Pay-in object |
payin.amount_changed |
The amount of a completed pay-in is changed by a dispute decision. The envelope has previous |
Pay-in object |
payout.completed |
The payout is executed (including again — when the amount is changed or by a dispute decision) | Payout object |
payout.failed |
The payout is canceled (see failureReason) |
Payout object |
dispute.opened |
A dispute is opened on a deal — by you or by Payin8 | Dispute object |
dispute.closed |
The dispute is closed; the result is in outcome |
Dispute object |
webhook.ping |
The "Send a check" button in the cabinet. It comes even if you are not subscribed to it | { "projectId", "message": "ping" } |
Only the events the project address is subscribed to come (except webhook.ping). For transitions without a webhook (client_paid, offered, in_progress), use GET — see Deal statuses.
The webhook data is the same object that GET returns for this deal or dispute in the same version. There is one difference: in the data of dispute.* events, the comment field is always null.
Envelope#
| Field | Type | Meaning |
|---|---|---|
id |
string (UUID) | The event ID. The same in all attempts and on resending |
type |
string | The event type |
apiVersion |
string | v1 |
createdAt |
string | When the event happened |
test |
boolean | Reserved; always false now |
data |
object | The deal or dispute object (see the event table) |
previous |
object | Only in payin.amount_changed: amount, fee, net before the change |
The event body is fixed at the moment of the event and is at most 32 KB; every attempt and every resend carries the same bytes.
Request headers#
| Header | Value |
|---|---|
Content-Type |
application/json |
User-Agent |
payin8-webhooks/1.0 |
Payin8-Signature |
The signature: t=<unix seconds>,v1=<hex>[,v1=<hex>] |
Payin8-Event-Id |
The event id — the same as id in the body |
Payin8-Event-Type |
The event type |
Payin8-Delivery-Id |
The delivery ID. Resending from the cabinet after the delivery has ended creates a new delivery with a new Payin8-Delivery-Id but the same event; while the delivery is still being retried, resending only brings forward the next attempt of the same delivery |
Payin8-Attempt |
The attempt number within the delivery: 1, 2, … |
Signature check#
Payin8-Signature: t=1795104473,v1=5b0c0f1e8a…(64 hex)
v1 = hex( HMAC-SHA256( key = the whole "whsec_…" secret in UTF-8, message = t + "." + raw body ) )- Take
tand allv1values from the header. - Compute HMAC-SHA256 of the string
t, a dot, and the raw bytes of the body — before parsing the JSON. The key is the whole secret string including thewhsec_prefix. - Accept the request if your value matches any
v1(compare in constant time) and|now − t|is at most 300 seconds.
There can be several v1 values after the secret is replaced in the cabinet: for some time the request is signed with both the new and the previous secret. t is the attempt time, so each attempt has its own signature.
The webhook secret is issued in the cabinet when the address is created and when the secret is replaced; after a replacement, the previous secret keeps signing requests as a second v1 for some time. Example secret: whsec_dGhpcy1pcy1hbi1leGFtcGxlLXdlYmhvb2sta2V5LTA (fictional).
// Payin8 webhook verification. Node.js 18+, no dependencies.
import { createHmac, timingSafeEqual } from 'node:crypto';
import { createServer } from 'node:http';
const WEBHOOK_SECRET = process.env.PAYIN8_WEBHOOK_SECRET ?? 'whsec_dGhpcy1pcy1hbi1leGFtcGxlLXdlYmhvb2sta2V5LTA';
/** true if the signature matches and the timestamp is not older than toleranceSec. rawBody — the body bytes as received. */
export function verifyPayin8Webhook(rawBody, signatureHeader, secret, toleranceSec = 300) {
if (typeof signatureHeader !== 'string') return false;
const parts = signatureHeader.split(',').map((p) => p.trim());
const t = parts.find((p) => p.startsWith('t='))?.slice(2) ?? '';
const signatures = parts.filter((p) => p.startsWith('v1=')).map((p) => p.slice(3));
if (!/^\d+$/.test(t) || Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false;
const expected = createHmac('sha256', secret)
.update(Buffer.concat([Buffer.from(`${t}.`, 'utf8'), Buffer.from(rawBody)]))
.digest();
return signatures.some((s) => {
const got = Buffer.from(s, 'hex');
return got.length === expected.length && timingSafeEqual(got, expected);
});
}
// Example receiver: check the signature, answer 200 at once, process the event after the answer.
const seen = new Set(); // in production code — a table of processed Payin8-Event-Id values
createServer((req, res) => {
const chunks = [];
req.on('data', (c) => chunks.push(c));
req.on('end', () => {
const raw = Buffer.concat(chunks);
if (!verifyPayin8Webhook(raw, req.headers['payin8-signature'], WEBHOOK_SECRET)) {
res.writeHead(400).end();
return;
}
res.writeHead(200).end();
const event = JSON.parse(raw.toString('utf8'));
if (seen.has(event.id)) return; // a repeat of the same delivery
seen.add(event.id);
console.log(event.type, event.data.id, event.data.status, event.data.version);
});
}).listen(Number(process.env.PORT ?? 3000));# Payin8 webhook verification. Python 3.8+, standard library only.
import hashlib
import hmac
import json
import os
import time
from http.server import BaseHTTPRequestHandler, HTTPServer
WEBHOOK_SECRET = os.environ.get("PAYIN8_WEBHOOK_SECRET", "whsec_dGhpcy1pcy1hbi1leGFtcGxlLXdlYmhvb2sta2V5LTA")
def verify_payin8_webhook(raw_body, signature_header, secret, tolerance_sec=300):
"""True if the signature matches and the timestamp is not older than tolerance_sec. raw_body — the body bytes as received."""
if not signature_header:
return False
parts = [p.strip() for p in signature_header.split(",")]
t = next((p[2:] for p in parts if p.startswith("t=")), "")
signatures = [p[3:] for p in parts if p.startswith("v1=")]
if not t.isdigit() or abs(time.time() - int(t)) > tolerance_sec:
return False
expected = hmac.new(secret.encode("utf-8"), t.encode("utf-8") + b"." + raw_body, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(expected, s.lower()) for s in signatures)
# Example receiver: check the signature, answer 200, process the event.
class Payin8WebhookHandler(BaseHTTPRequestHandler):
seen = set() # in production code — a table of processed Payin8-Event-Id values
def do_POST(self):
raw = self.rfile.read(int(self.headers.get("Content-Length", 0)))
if not verify_payin8_webhook(raw, self.headers.get("Payin8-Signature"), WEBHOOK_SECRET):
self.send_response(400)
self.end_headers()
return
self.send_response(200)
self.end_headers()
event = json.loads(raw)
if event["id"] in self.seen:
return
self.seen.add(event["id"])
print(event["type"], event["data"]["id"], event["data"].get("status"), event["data"].get("version"))
if __name__ == "__main__":
HTTPServer(("0.0.0.0", int(os.environ.get("PORT", "3000"))), Payin8WebhookHandler).serve_forever()<?php
// Payin8 webhook verification. PHP 7.4+.
/** true if the signature matches and the timestamp is not older than $toleranceSec. $rawBody — the body as received. */
function payin8_verify_webhook(string $rawBody, ?string $signatureHeader, string $secret, int $toleranceSec = 300): bool
{
if ($signatureHeader === null || $signatureHeader === '') {
return false;
}
$t = '';
$signatures = [];
foreach (explode(',', $signatureHeader) as $part) {
$part = trim($part);
if (strncmp($part, 't=', 2) === 0) {
$t = substr($part, 2);
} elseif (strncmp($part, 'v1=', 3) === 0) {
$signatures[] = strtolower(substr($part, 3));
}
}
if (!ctype_digit($t) || abs(time() - (int) $t) > $toleranceSec) {
return false;
}
$expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
foreach ($signatures as $signature) {
if (hash_equals($expected, $signature)) {
return true;
}
}
return false;
}
// Handler (this same file behind a web server): check the signature, answer 200, process the event.
$secret = getenv('PAYIN8_WEBHOOK_SECRET') ?: 'whsec_dGhpcy1pcy1hbi1leGFtcGxlLXdlYmhvb2sta2V5LTA';
$raw = file_get_contents('php://input');
if (!payin8_verify_webhook($raw, $_SERVER['HTTP_PAYIN8_SIGNATURE'] ?? null, $secret)) {
http_response_code(400);
exit;
}
$event = json_decode($raw, true);
// Here: if $event['id'] is already processed, do nothing; otherwise store the event for processing.
error_log($event['type'] . ' ' . $event['data']['id'] . ' v' . ($event['data']['version'] ?? '-'));
http_response_code(200);Warning
Check the signature against the raw body bytes. If your framework has already parsed the JSON and you serialize it again, the bytes can change, and the signature will not match.
How to respond#
- Any
2xxresponse means the delivery succeeded. The response body is not used. - The response must come within 10 seconds, and the connection must be established within 5 seconds (default values). Do not process the event before responding: store it and respond
200, then process it separately. - Any other code, a
3xxredirect, a timeout or a connection error is a failed attempt and will be retried. - Respond
2xxto an event you have already processed too: otherwise Payin8 keeps retrying its delivery.
Retries#
After a failed attempt, the delivery is retried with a growing pause within a window counted from the delivery creation. The schedule is a Payin8 setting; by default the window is 24 hours, the pause after the first failure is 10 seconds, then it doubles (20 s, 40 s, 80 s, …) up to 6 hours; each pause has a ±10% spread. The last attempt is at the end of the window; with the default schedule there are up to 16 attempts in total. If delivery does not succeed within the window, it stops.
| Attempt | Approximately after (from the first), by default |
|---|---|
| 1 | at once |
| 2 | 10 s |
| 3 | 30 s |
| 4 | 1 min 10 s |
| 5 | 2.5 min |
| 6 | 5 min |
| 7 | 10.5 min |
| 8 | 21 min |
| 9 | 42.5 min |
| 10 | 1 h 25 min |
| 11 | 2 h 50 min |
| 12 | 5 h 40 min |
| 13 | 11 h 23 min |
| 14 | 17 h 23 min |
| 15 | 23 h 23 min |
| 16 | 24 h |
- All attempts carry the same body, the same
Payin8-Event-IdandPayin8-Delivery-Id;Payin8-Attemptgrows, and the signature is computed again. - If the webhook address is switched off or deleted, undelivered events are no longer sent.
- Events that were not sent (there was no address, it was switched off, or there was no subscription) stay in the project log; you can send an event again to the current project address from the cabinet while the event is kept in the log (90 days by default; see Webhooks). If the delivery of this event is still being retried, resending only brings forward its next attempt; otherwise a new delivery of the same event is created, with the same body and a new retry window.
Order and duplicates#
- Order is not guaranteed. Deliveries run in parallel and are retried independently:
payin.completedcan come beforepayin.assigned, andpayin.failedof an expired pay-in can come after thepayin.completedof a late confirmation. - Duplicates are possible. One event can come several times: after a retry, after resending from the cabinet, after a failure on either side.
How to process:
- Check the signature.
- If the event with this
id(Payin8-Event-Id) is already processed, respond200and do nothing. - Compare
data.versionwith the deal version you have already stored. Less or equal — the state is outdated: record the event, but do not roll back the status. Greater — apply it. - Match the deal by
data.id(ordata.invoiceId/data.invoiceIds), not by the order of arrival. - Before crediting money to the client, make sure that
data.status=completed; finality is given bydata.final(see Final outcome).
If webhooks do not come for a long time, reconcile with GET /v1/payins/{id} and GET /v1/payouts/{id} — their responses have the same format and the same version.
Payment details in the webhook#
With flow: requisite, the payin.assigned webhook contains the payment details (data.requisite); in other events the payment details are null. The payment details of such a pay-in count as issued to you as soon as an executor is assigned: through the webhook, if the project address is subscribed to payin.assigned (on a cancellation attempt — requisite_already_shown with via: "webhook"), otherwise through the API (via: "api").
Event examples#
payin.assigned#
{
"id": "6f0e1d2c-3b4a-4958-8776-655443322110",
"type": "payin.assigned",
"apiVersion": "v1",
"createdAt": "2026-11-19T16:07:53.975Z",
"test": false,
"data": {
"id": "3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44",
"object": "payin",
"invoiceId": "inv-100501",
"invoiceIds": ["inv-100501"],
"status": "awaiting_payment",
"final": false,
"flow": "requisite",
"method": "bank_transfer",
"currency": "ARS",
"requestedAmount": "15000.00",
"amount": "15000.00",
"fee": "375.00",
"net": "14625.00",
"customer": { "id": "client-42", "name": "Juan Perez" },
"paymentUrl": null,
"requisite": {
"type": "cvu",
"number": "0000003110000987654323",
"alias": null,
"holderName": "Martin Suarez",
"holderTaxId": null,
"bankName": "Banco Ejemplo"
},
"expiresAt": "2026-11-19T16:16:53.925Z",
"failureReason": null,
"dispute": null,
"returnUrls": { "success": "https://shop.example.com/pay/ok", "fail": null, "back": null },
"locale": "en",
"metadata": { "orderId": "A-1001" },
"test": false,
"version": 2,
"createdAt": "2026-11-19T16:07:53.910Z",
"updatedAt": "2026-11-19T16:07:53.957Z",
"assignedAt": "2026-11-19T16:07:53.925Z",
"clientPaidAt": null,
"completedAt": null,
"expiredAt": null,
"canceledAt": null
}
}payin.failed#
The payment term expired. final: false: the money can still come within the late confirmation window. Meanwhile, a second number of the same client was joined to the pay-in (invoiceIds).
{
"id": "6f0e1d2c-3b4a-4958-8776-655443322111",
"type": "payin.failed",
"apiVersion": "v1",
"createdAt": "2026-11-19T16:16:55.678Z",
"test": false,
"data": {
"id": "3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44",
"object": "payin",
"invoiceId": "inv-100501",
"invoiceIds": ["inv-100501", "inv-100502"],
"status": "expired",
"final": false,
"flow": "requisite",
"method": "bank_transfer",
"currency": "ARS",
"requestedAmount": "15000.00",
"amount": "15000.00",
"fee": "375.00",
"net": "14625.00",
"customer": { "id": "client-42", "name": "Juan Perez" },
"paymentUrl": null,
"requisite": null,
"expiresAt": "2026-11-19T16:16:53.925Z",
"failureReason": "expired",
"dispute": null,
"returnUrls": { "success": "https://shop.example.com/pay/ok", "fail": null, "back": null },
"locale": "en",
"metadata": { "orderId": "A-1001" },
"test": false,
"version": 4,
"createdAt": "2026-11-19T16:07:53.910Z",
"updatedAt": "2026-11-19T16:16:55.665Z",
"assignedAt": "2026-11-19T16:07:53.925Z",
"clientPaidAt": null,
"completedAt": null,
"expiredAt": "2026-11-19T16:16:55.661Z",
"canceledAt": null
}
}payin.completed#
The same pay-in is completed after the term for the amount that actually came, 14,800.00: amount, fee and net are recalculated.
{
"id": "6f0e1d2c-3b4a-4958-8776-655443322112",
"type": "payin.completed",
"apiVersion": "v1",
"createdAt": "2026-11-19T16:17:06.246Z",
"test": false,
"data": {
"id": "3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44",
"object": "payin",
"invoiceId": "inv-100501",
"invoiceIds": ["inv-100501", "inv-100502"],
"status": "completed",
"final": true,
"flow": "requisite",
"method": "bank_transfer",
"currency": "ARS",
"requestedAmount": "15000.00",
"amount": "14800.00",
"fee": "370.00",
"net": "14430.00",
"customer": { "id": "client-42", "name": "Juan Perez" },
"paymentUrl": null,
"requisite": null,
"expiresAt": "2026-11-19T16:16:53.925Z",
"failureReason": null,
"dispute": null,
"returnUrls": { "success": "https://shop.example.com/pay/ok", "fail": null, "back": null },
"locale": "en",
"metadata": { "orderId": "A-1001" },
"test": false,
"version": 5,
"createdAt": "2026-11-19T16:07:53.910Z",
"updatedAt": "2026-11-19T16:17:06.219Z",
"assignedAt": "2026-11-19T16:07:53.925Z",
"clientPaidAt": null,
"completedAt": "2026-11-19T16:17:06.217Z",
"expiredAt": "2026-11-19T16:16:55.661Z",
"canceledAt": null
}
}payin.amount_changed#
You opened an amount_mismatch dispute, and Payin8 changed the amount of the completed pay-in to 14,500.00. The dispute is still open at this moment (dispute.status: "open", final: false); dispute.closed comes next.
{
"id": "6f0e1d2c-3b4a-4958-8776-655443322113",
"type": "payin.amount_changed",
"apiVersion": "v1",
"createdAt": "2026-11-19T16:21:32.085Z",
"test": false,
"data": {
"id": "3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44",
"object": "payin",
"invoiceId": "inv-100501",
"invoiceIds": ["inv-100501", "inv-100502"],
"status": "completed",
"final": false,
"flow": "requisite",
"method": "bank_transfer",
"currency": "ARS",
"requestedAmount": "15000.00",
"amount": "14500.00",
"fee": "362.50",
"net": "14137.50",
"customer": { "id": "client-42", "name": "Juan Perez" },
"paymentUrl": null,
"requisite": null,
"expiresAt": "2026-11-19T16:16:53.925Z",
"failureReason": null,
"dispute": { "id": "c2a1b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "status": "open" },
"returnUrls": { "success": "https://shop.example.com/pay/ok", "fail": null, "back": null },
"locale": "en",
"metadata": { "orderId": "A-1001" },
"test": false,
"version": 7,
"createdAt": "2026-11-19T16:07:53.910Z",
"updatedAt": "2026-11-19T16:21:32.083Z",
"assignedAt": "2026-11-19T16:07:53.925Z",
"clientPaidAt": null,
"completedAt": "2026-11-19T16:17:06.217Z",
"expiredAt": "2026-11-19T16:16:55.661Z",
"canceledAt": null
},
"previous": { "amount": "14800.00", "fee": "370.00", "net": "14430.00" }
}payout.completed#
{
"id": "6f0e1d2c-3b4a-4958-8776-655443322114",
"type": "payout.completed",
"apiVersion": "v1",
"createdAt": "2026-11-19T16:09:48.859Z",
"test": false,
"data": {
"id": "7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f",
"object": "payout",
"invoiceId": "wd-200731",
"invoiceIds": ["wd-200731"],
"status": "completed",
"final": true,
"method": "bank_transfer",
"currency": "ARS",
"amount": "20000.00",
"feePayer": "merchant",
"fee": "200.00",
"requestedFee": "200.00",
"totalDebit": "20200.00",
"recipientAmount": "20000.00",
"paidAmount": "20000.00",
"refundedAmount": "0.00",
"bankReference": "BR-55120397",
"recipient": {
"type": "cvu",
"account": "0000003110000123456781",
"holderName": "Maria Gomez",
"taxId": "20312345677"
},
"customer": { "id": "client-77", "name": "Maria Gomez" },
"receipts": [
{
"id": "5d2e8f1a-9c3b-4a7d-b6e5-0f1e2d3c4b5a",
"name": "transfer-receipt.png",
"contentType": "image/png",
"size": 84210,
"uploadedAt": "2026-11-19T16:09:48.763Z"
}
],
"failureReason": null,
"dispute": null,
"metadata": { "withdrawalId": "W-77" },
"test": false,
"version": 4,
"createdAt": "2026-11-19T16:09:23.307Z",
"updatedAt": "2026-11-19T16:09:48.852Z",
"expiresAt": "2026-11-19T20:09:23.292Z",
"startedAt": "2026-11-19T16:09:31.447Z",
"completedAt": "2026-11-19T16:09:48.814Z",
"canceledAt": null
}
}payout.failed#
Another outcome of the same payout: you canceled it before an executor took it. The held amount returned in full.
{
"id": "6f0e1d2c-3b4a-4958-8776-655443322115",
"type": "payout.failed",
"apiVersion": "v1",
"createdAt": "2026-11-19T16:09:43.514Z",
"test": false,
"data": {
"id": "7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f",
"object": "payout",
"invoiceId": "wd-200731",
"invoiceIds": ["wd-200731"],
"status": "canceled",
"final": true,
"method": "bank_transfer",
"currency": "ARS",
"amount": "20000.00",
"feePayer": "merchant",
"fee": "0.00",
"requestedFee": "200.00",
"totalDebit": "20200.00",
"recipientAmount": "20000.00",
"paidAmount": "0.00",
"refundedAmount": "20200.00",
"bankReference": null,
"recipient": {
"type": "cvu",
"account": "0000003110000123456781",
"holderName": "Maria Gomez",
"taxId": "20312345677"
},
"customer": { "id": "client-77", "name": "Maria Gomez" },
"receipts": [],
"failureReason": "canceled_by_merchant",
"dispute": null,
"metadata": { "withdrawalId": "W-77" },
"test": false,
"version": 2,
"createdAt": "2026-11-19T16:09:23.307Z",
"updatedAt": "2026-11-19T16:09:43.505Z",
"expiresAt": "2026-11-19T20:09:23.292Z",
"startedAt": null,
"completedAt": null,
"canceledAt": "2026-11-19T16:09:43.485Z"
}
}dispute.opened#
{
"id": "6f0e1d2c-3b4a-4958-8776-655443322116",
"type": "dispute.opened",
"apiVersion": "v1",
"createdAt": "2026-11-19T16:20:18.856Z",
"test": false,
"data": {
"id": "c2a1b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"object": "dispute",
"dealId": "3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44",
"dealType": "payin",
"invoiceId": "inv-100501",
"status": "open",
"reason": "amount_mismatch",
"comment": null,
"claimedAmount": "14500.00",
"outcome": null,
"resolvedAmount": null,
"files": [
{
"id": "9e1d2c3b-4a5f-4e6d-8c7b-6a5f4e3d2c1b",
"name": "bank-statement.pdf",
"contentType": "application/pdf",
"size": 48213,
"uploadedAt": "2026-11-19T16:20:12.480Z"
}
],
"openedAt": "2026-11-19T16:20:18.841Z",
"closedAt": null
}
}dispute.closed#
{
"id": "6f0e1d2c-3b4a-4958-8776-655443322117",
"type": "dispute.closed",
"apiVersion": "v1",
"createdAt": "2026-11-19T16:21:32.094Z",
"test": false,
"data": {
"id": "c2a1b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"object": "dispute",
"dealId": "3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44",
"dealType": "payin",
"invoiceId": "inv-100501",
"status": "closed",
"reason": "amount_mismatch",
"comment": null,
"claimedAmount": "14500.00",
"outcome": "amount_changed",
"resolvedAmount": "14500.00",
"files": [
{
"id": "9e1d2c3b-4a5f-4e6d-8c7b-6a5f4e3d2c1b",
"name": "bank-statement.pdf",
"contentType": "application/pdf",
"size": 48213,
"uploadedAt": "2026-11-19T16:20:12.480Z"
}
],
"openedAt": "2026-11-19T16:20:18.841Z",
"closedAt": "2026-11-19T16:21:32.090Z"
}
}webhook.ping#
{
"id": "6f0e1d2c-3b4a-4958-8776-655443322118",
"type": "webhook.ping",
"apiVersion": "v1",
"createdAt": "2026-11-19T05:59:30.218Z",
"test": false,
"data": {
"projectId": "e4d3c2b1-a0f9-4e8d-9c7b-6a5d4c3b2a10",
"message": "ping"
}
}API
Retries, lists and limits#
How to retry requests safely, page through lists, and which limits apply to requests.
Idempotent creation#
The idempotency key of creation is your invoiceId. It is unique within the merchant, separately for pay-ins and for payouts: you can give the same number to one pay-in and one payout.
| Situation | Response |
|---|---|
The first request with this invoiceId |
201 (a pay-in can also get 202) — the deal is created |
| A repeat with the same parameters | 200, the Idempotent-Replayed: true header, the same deal in its current state |
| A repeat with different parameters | 409 idempotency_conflict, details.id is the id of the deal already created |
| The number is taken by a deal of another project of the merchant | 409 invoice_id_taken |
What is compared on a repeat:
- a pay-in —
amount,currency,method,flow,customer.id,customer.name,customer.email,returnUrls,locale,metadata;waitSecandcustomer.ipare not compared. For a number joined to a pay-in of the same client,amount,currency,methodandcustomer.idare compared; - a payout —
amount,currency,method,feePayer,recipient(after normalization: the number without spaces and hyphens, the alias in lowercase, collapsed spaces in the name),customer.id,customer.name,metadata.
A repeat of a pay-in creation with flow: requisite also waits for an executor to be assigned, up to waitSec.
The other operations are safe to repeat too:
| Operation | Repeat |
|---|---|
POST /v1/payins/{id}/cancel, POST /v1/payouts/{id}/cancel |
An already canceled deal — 200 with its current state |
POST /v1/files |
The same bytes to the same deal with the same purpose — 200 with the file uploaded earlier |
POST /v1/disputes |
The deal already has an open dispute — 200 with it; the comment and the files are added to the dispute |
POST /v1/disputes/{id}/evidence |
Each call adds a message to the dispute; repeat only the calls that failed |
Retrying after a failure#
Each retry is a new request: a new X-Timestamp and X-Nonce, a new signature (see Authentication). The body and the invoiceId stay the same.
| What happened | What to do |
|---|---|
| A dropped connection, a timeout, no response | Repeat the same request. If the deal was created, the repeat returns it with 200 |
429 rate_limited |
Retry after Retry-After seconds |
503 with the code busy, tx_timeout, service_restarting, dependency_unavailable, nonce_store_unavailable |
Nothing was written; retry in a few seconds |
409 concurrent_update, 409 lock_busy |
The deal was being changed at the same time; retry |
500 internal_error |
The outcome is unknown. Check with GET /v1/payins/by-invoice/{invoiceId} (or …/payouts/…), then retry with the same invoiceId if needed |
409 idempotency_conflict |
Do not retry: the number is already taken by a deal with different parameters. Find it by details.id |
Other 4xx |
Do not retry without fixing the request |
Use an increasing delay between retries and limit their number.
Pagination and filters#
The GET /v1/payins, GET /v1/payouts and GET /v1/disputes lists are paginated with a cursor.
limit— the page size, 1–100, 50 by default.- The response:
{ "items": [...], "nextCursor": "…" }. WhilenextCursoris notnull, pass it in thecursorparameter of the next request together with the same filters. - The cursor is opaque: do not parse or build it yourself. A corrupted cursor gets
400 validation_failedfor thecursorfield. - Sorting: pay-ins and payouts — by
createdAt, newest first; disputes — byopenedAt, newest first.
The period for pay-ins and payouts. The filter is by createdAt: createdFrom is inclusive, createdTo is exclusive.
| Sent | Period |
|---|---|
| Nothing | The last 7 days up to now |
Only createdFrom |
The longest allowed period from createdFrom |
Only createdTo |
7 days before createdTo |
| Both | As set; no longer than the longest allowed period |
The longest period is a platform setting, 31 days by default. A createdFrom that is not earlier than createdTo, or a period longer than allowed, gets 400 validation_failed. To export a longer period, split it into parts.
Filters: pay-ins and payouts — status, customerId, createdFrom, createdTo; disputes — status (open, closed) and dealId. A query parameter is signed exactly as it is sent (see Canonical string).
Limits#
The numeric limits, except metadata, are platform or project settings; the table shows the default values, and the values in effect can differ.
| What | Limit | When exceeded |
|---|---|---|
| Request rate of one key | 3000 requests per minute (the window is a calendar minute) | 429 rate_limited, details.retryAfterSec, the Retry-After header |
| JSON request body size | 1 MB | 413 payload_too_large |
A file in POST /v1/files |
10 MB per file; up to 10 of your files per deal (any purpose); 30 MB of all files of a deal; 2 GB of the merchant's uploads per day |
413 file_too_large, 409 files_limit_reached, 413 files_quota_exceeded |
Open pay-ins of one client (customer.id) in a project |
3 | 409 customer_open_payins_limit, details.limit |
| Payment details issued to a project: distinct accounts per rolling hour | 300 | 429 requisite_reveal_limit, details.kind: "distinct_requisites_per_hour" |
Open flow: requisite pay-ins of a project |
200 | 429 requisite_reveal_limit, details.kind: "open_requisite_payins" |
| List period | 31 days | 400 validation_failed |
metadata |
10 keys [A-Za-z0-9_]{1,40}, values up to 256 characters |
400 validation_failed |
waitSec |
20 seconds | 400 validation_failed |
The value in effect for the client limit and the payment details limits comes in details.limit of the error; the deal file limit comes in details.limit of the files_limit_reached error; the size limit comes in details.maxBytes.
The payment details limits and the client open pay-in limit are checked before the deal is created: a rejection creates nothing. requisite_reveal_limit does not carry Retry-After: retry later, when some of the pay-ins close.
API
Errors#
An unsuccessful response is a 4xx or 5xx HTTP status with a body in one format.
Error format#
{
"code": "validation_failed",
"message": "Validation failed",
"details": {
"fields": [
{ "path": "amount", "errors": ["amount must be a decimal string with at most 13 integer and 6 fraction digits"] },
{ "path": "customer.email", "errors": ["email must be an email"] }
]
}
}| Field | Type | Meaning |
|---|---|---|
code |
string | The machine-readable error code. It is stable — build your handling on it |
message |
string | A description in English for your logs. The text can change; do not parse it |
details |
object | Details; not every error has them. The contents are in the catalog below |
For validation_failed, details.fields is a list of fields: path is the field name with dots (customer.email, recipient.account), errors says what is wrong. Validation has two stages: first the format of all fields (errors for all fields come together, as in the example), then the values that depend on the currency and the settings (for example, the number of decimal places of the currency: amount must be a decimal string with at most 2 fraction digits); such errors come only when the format is already correct.
Every response, including an error, has the X-Request-Id header: include it when you contact support.
Code catalog#
Request and format#
code |
HTTP | When | What to do |
|---|---|---|---|
validation_failed |
400 | A body field, a path or query parameter failed validation; an extra field in the body; details.fields |
Fix the request |
malformed_json |
400 | The body is not JSON | Fix the serialization |
bad_request |
400 | The body could not be read | Check Content-Type and the body |
route_not_found |
404 | There is no such method and path | Check the path and the method |
not_found |
404 | The deal, dispute or file is not in the key's project | Check the id; make sure you use the key of that project |
payload_too_large |
413 | The request body is too large | Reduce the body |
http_<status> |
4xx | Other request reading errors (for example, http_415 — an unsupported body encoding) |
Send JSON in UTF-8 |
Authentication and access#
code |
HTTP | When | What to do |
|---|---|---|---|
signature_missing |
401 | X-Api-Key, X-Timestamp, X-Nonce or X-Signature is missing |
Send all four headers |
nonce_invalid |
401 | X-Nonce is not 16–64 characters A–Z a–z 0–9 _ - |
Fix the nonce generation |
api_key_invalid |
401 | The key does not exist, is revoked or has expired | Check the key; issue a new one |
timestamp_out_of_window |
401 | X-Timestamp is outside the window; details.serverTime |
Synchronize the clock and sign again |
signature_invalid |
401 | The signature does not match | Check the canonical string |
nonce_replayed |
401 | X-Nonce has already been used |
Use a new nonce for every request |
ip_not_allowed |
403 | The sender address is not in the key's IP list | Add the address to the key's list |
ip_allowlist_required |
403 | The operation needs a key with an IP list; details.code |
Set an IP list on the key |
permission_denied |
403 | The key has no right; details.code |
Grant the right to the key |
tenant_blocked |
403 | The merchant is blocked | Contact support |
project_disabled |
403 | The project is disabled | Contact support |
forbidden |
403 | Access is denied | Contact support with the X-Request-Id |
rate_limited |
429 | The key's per-minute request limit is exceeded; details.retryAfterSec, the Retry-After header |
Retry after the given time |
Deals#
code |
HTTP | When | What to do |
|---|---|---|---|
idempotency_conflict |
409 | The invoiceId was already used with other parameters; details.id |
Do not retry; get the deal by details.id or choose a new number |
invoice_id_taken |
409 | The invoiceId is taken by a deal of another project of the merchant |
Choose another number |
customer_open_payins_limit |
409 | The client has the maximum number of open pay-ins; details.limit |
Wait until the client's pay-ins close |
insufficient_balance |
409 | Not enough balance for the payout; details.currency, details.available, details.required |
Top up the balance or reduce the amount |
invalid_state |
409 | The action is not possible in the current status; details.status |
Read the deal again |
requisite_already_shown |
409 | Pay-in cancellation after the payment details were issued; details.shownAt, details.via |
Wait until the pay-in term expires |
dispute_open |
409 | A dispute is open on the deal; details.disputeId |
Wait for the dispute decision |
concurrent_update |
409 | The deal was being changed at the same time | Retry the request |
lock_busy |
409 | The resource is busy | Retry the request |
conflict |
409 | A write conflict | Read the deal again; retry if needed |
method_unavailable |
422 | The method, currency or direction is not enabled for the project; details.method, details.currency, details.direction |
Check GET /v1/methods |
amount_out_of_range |
422 | The amount is outside the method limits; details.min, details.max |
Change the amount |
invalid_recipient |
422 | The recipient's account, name or CUIT is invalid; details.field, details.rule (format or checksum) |
Fix the recipient data |
fee_payer_unavailable |
422 | The feePayer is not allowed; details.allowed |
Send a value from details.allowed or omit the field |
feature_unavailable |
422 | The feature is not available; details.feature (for example, widget) |
Use another way or contact support |
negative_margin |
422 | The deal cannot be processed with the current tariff terms | Contact support |
requisite_reveal_limit |
429 | The project's limit on issuing payment details is used up; details.limit, details.kind |
Retry later |
no_widget_domain |
500 | flow: widget, but the project has no active payment page address; the deal is not created |
Contact support |
Files and disputes#
code |
HTTP | When | What to do |
|---|---|---|---|
file_type_not_allowed |
415 | The file is not PDF, PNG, JPEG or WebP, or it is empty; details.allowed |
Upload a file of an allowed type |
file_too_large |
413 | The file is over the limit; details.maxBytes |
Reduce the file |
files_quota_exceeded |
413 | The file storage quota is used up; details.quota, details.limitBytes |
Retry later or contact support |
files_limit_reached |
409 | The deal has the maximum number of your files; details.limit |
— |
file_not_attachable |
422 | The file cannot be attached to the dispute; details.fileId, details.why |
Upload the file to this deal with purpose=evidence |
files_storage_unavailable |
503 | Uploads are temporarily suspended | Retry later |
dispute_not_allowed |
409 | A dispute cannot be opened; details.why: reason, status, window |
See the opening conditions |
Temporary failures#
code |
HTTP | When | What to do |
|---|---|---|---|
internal_error |
500 | An internal error; the operation outcome is unknown | Check the state with GET (by invoiceId), then retry |
busy |
503 | The service is busy; nothing was written | Retry in a few seconds |
tx_timeout |
503 | The operation did not complete in time; nothing was written | Retry |
service_restarting |
503 | The service is restarting; nothing was written | Retry in a few seconds |
dependency_unavailable |
503 | Temporarily unavailable | Retry later |
nonce_store_unavailable |
503 | Request verification is temporarily unavailable | Retry with a new signature |
How to retry requests: Retrying after a failure.