Payin8Docs

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.

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#

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. 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.
  9. 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.
  10. 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).

  1. Open the invitation link. The "Invitation" page shows the role you will get and how long the link is valid ("Valid until").
  2. Enter your name ("Your name (optional)"), then "New password" and "Repeat the password".
  3. 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#

  1. On the "Sign in" page, enter "E-mail" and "Password" and click "Sign in".
  2. 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:

  1. 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".
  2. Enter the "Current password" and click "Start".
  3. 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.
  4. 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-Key header;
  • secret — kept only by you; it is used to compute the X-Signature signature. 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#

  1. Connection → API keys → "Issue a key".
  2. 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).
  3. Confirm with a code from the app.
  4. "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 /24 for IPv4 and /56 for 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#

  1. Connection → Projects → project → "Webhook" tab.
  2. Click "Set up" (if no address is set yet) or "Change".
  3. 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.
  4. 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 443 or 8443 (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.

  1. 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".
  2. Transfer USDT (TRC-20) to this address from your wallet.
  3. 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:

  1. Click "Add an address".
  2. "Address" — paste it from your wallet. A TRON address starts with T and has 34 characters; Payin8 checks the checksum.
  3. "Label" — 1 to 64 characters: how the address is named in the cabinet.
  4. 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#

  1. Open the deal and click "Open a dispute".
  2. 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".
  3. "Comment" — what happened, what the client says, what you expect. Up to 4000 characters; mandatory for the "Other" reason.
  4. For a pay-in — "How much the client paid" (optional, the amount from the client's receipt).
  5. 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.
  6. 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#

  1. Team → "Invite".
  2. Enter "E-mail", "Name" (optional) and "Role".
  3. Click "Create invitation" and confirm with a code from the app.
  4. 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#

  1. While Payin8 is finding payment details — a waiting screen asking not to close the page.
  2. 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.
  3. A field for the transfer receipt — mandatory or optional, depending on the "Client receipt required" rule.
  4. A button for the client to report the transfer, and a button to cancel the payment.
  5. 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).

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 /24 for IPv4 and /56 for 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 2xx fast 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#

  1. 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 secret ms_… (see API keys).
  2. 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 answer 200 means the signature works. If not, compare your values with the worked example.
  3. Check the terms. GET /v1/methods shows which methods and directions are on for the project, the amount limits and the fees (see Methods).
  4. 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 answers 2xx at once (see How to respond). The "Send a check" button sends webhook.ping: it lets you test the handler before the first deal.
  5. Create a pay-in. POST /v1/payins with your invoiceId, the amount, the client and the mode flow (see Create a pay-in). With flow: requisite, show the client the requisite and the amount from the answer or from the payin.assigned webhook; with flow: widget, send the client to paymentUrl.
  6. Get the result. The outcome comes in the payin.completed or payin.failed webhook; you can always read the current state with GET /v1/payins/{id} or by your number (see Get by number).
  7. Handle failures. After a timeout or a 5xx, repeat the creation with the same invoiceId: a second deal is not created (see Idempotency).

Before going live, go through the checklist.

Base URL and version#

https://api.payin8.io

All 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/json header. The exception is a file upload: the body of POST /v1/files is 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. ARS has 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 is bank_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 createdFrom and createdTo list filters accept ISO 8601 (2026-11-19T00:00:00Z).
  • The X-Timestamp signature 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#

  1. Your server creates a pay-in: POST /v1/payins with the amount, the client and the pay-in mode (flow).
  2. Payin8 finds an executor and their bank account (payment details). The pay-in moves from created to awaiting_payment, and the payin.assigned webhook arrives. The payment term is the expiresAt field.
  3. The client transfers the money to the payment details: with flow: requisite you show the payment details and the amount to the client, with flow: widget the Payin8 payment page at the paymentUrl link does it.
  4. The receipt of funds is confirmed — the pay-in is completed, and the payin.completed webhook arrives. net = amount − fee is credited to the balance.
  5. If there was no payment in time or no executor was found — expired or canceled, and the payin.failed webhook.

Details: Pay-ins and Deal statuses.

How a payout works#

  1. Your server creates a payout: POST /v1/payouts with the amount and the recipient's account. totalDebit = amount + fee is held on the balance, and the payout is offered to executors (offered).
  2. An executor takes the payout (in_progress), transfers the money to the recipient and attaches a receipt.
  3. The payout is completed, and the payout.completed webhook arrives; you can download the receipt (GET /v1/payouts/{id}/receipts/{fileId}).
  4. If nobody took the payout in time, it was canceled, or the transfer is impossible — canceled, the payout.failed webhook, 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 string e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.

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:

HTTP
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:

30c3d1602c2e005c5f61912a5e56f9654cfa6b4488ebc502d77e0df913ae6122

The canonical string:

v1
POST
/v1/payins
1795104000
3f9c2a7d1b6e4f08a5c3d2e1f0a9b8c7
30c3d1602c2e005c5f61912a5e56f9654cfa6b4488ebc502d77e0df913ae6122

The signature header:

X-Signature: v1=c4acc4e91400077869ed47cba8b1b4291da546d9e03508505f61a0dd182a8f19

For 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-Timestamp must differ from the Payin8 server time by no more than the allowed window in either direction (300 seconds by default); otherwise you get 401 timestamp_out_of_window. The details.serverTime of 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-Nonce twice with the same key: a repeat gets 401 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-Timestamp and X-Nonce, a new signature. A safe retry of creation relies on invoiceId (see Idempotency), not on the nonce.

Order of checks#

Payin8 checks a request in this order and responds with the first error it finds:

  1. The four signature headers are present; the X-Nonce format.
  2. The key: it exists, it is active, it is a merchant API key.
  3. X-Timestamp is within the window.
  4. The signature.
  5. X-Nonce has not been used.
  6. The sender address is in the key's IP list (if the list is set).
  7. The merchant and the project are active.
  8. The key has the right for this endpoint.
  9. For payout creation — the key has a non-empty IP list (see below).
  10. 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 get 403 ip_allowlist_required, with the operation code in details.code (merchant_api.payouts.create or merchant_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"
}

To check: a GET /v1/balance call must return 200 and your balance.

payin8 GET /v1/balance

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

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

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-0d7e2c9b1a44

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-100501

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"

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 created status (no executor assigned yet);
  • a flow: widget pay-in in the awaiting_payment status, 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/cancel

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.

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

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-1a2b3c4d5e6f

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-200731

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"

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

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/cancel

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
JSON
{
  "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/balance

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

JSON
{
  "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/methods

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-Type set to the file type (for example, application/pdf);
  • a multipart/form-data form with the file in the file part.

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-Type header and the extension in the name do not affect it. Another type or an empty file gets 415 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.maxBytes is 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 a multipart form).
  • A deal can have at most 10 of your files (the default value; files with any purpose count) — otherwise 409 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.png uploaded as a PDF becomes scan.pdf).
  • Uploading the same bytes with the same purpose to the same deal again does not create a new file: the response is 200 with 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
JSON
{
  "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/pdf

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, completed statuses, and also canceled if an executor was assigned.
  • A payout — in the in_progress and completed statuses.
  • No later than the set term after the deal was created (7 days by default); the term is in details.until of the window rejection.

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:

JSON
{
  "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"]}'

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-0e1f2a3b4c5d

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"

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"]}'

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. While final: 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 canceled with failureReason: 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 become completed if the money does come. The window starts at expiresAt; while it is open, an expired pay-in has final: 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 at expiresAt. If the executor does not attach a receipt for a long time, Payin8 opens a dispute on the payout itself — it comes as the dispute.opened webhook with reason: 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: completed or canceled without a dispute; expired — after the late confirmation window closes;
  • payout: completed or canceled without 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 ) )
  1. Take t and all v1 values from the header.
  2. 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 the whsec_ prefix.
  3. 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));

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 2xx response 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 3xx redirect, a timeout or a connection error is a failed attempt and will be retried.
  • Respond 2xx to 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-Id and Payin8-Delivery-Id; Payin8-Attempt grows, 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.completed can come before payin.assigned, and payin.failed of an expired pay-in can come after the payin.completed of 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:

  1. Check the signature.
  2. If the event with this id (Payin8-Event-Id) is already processed, respond 200 and do nothing.
  3. Compare data.version with 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.
  4. Match the deal by data.id (or data.invoiceId / data.invoiceIds), not by the order of arrival.
  5. Before crediting money to the client, make sure that data.status = completed; finality is given by data.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#

JSON
{
  "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).

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

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

JSON
{
  "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#

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

JSON
{
  "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#

JSON
{
  "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#

JSON
{
  "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#

JSON
{
  "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; waitSec and customer.ip are not compared. For a number joined to a pay-in of the same client, amount, currency, method and customer.id are 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": "…" }. While nextCursor is not null, pass it in the cursor parameter 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_failed for the cursor field.
  • Sorting: pay-ins and payouts — by createdAt, newest first; disputes — by openedAt, 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#

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