API Integration

Learn how to integrate with the Tapaya Platform API to manage merchants and organization settings.

The Tapaya Platform API allows you to manage your integration server-side. Which endpoints you need depends on how your app takes payments; not every integrator needs every section below.

Swagger Documentation

Explore the full capabilities of the Tapaya API and build your own system on top of it using our Swagger documentation.

Which sections apply to you

Your integration	Merchant Authentication	Merchant Onboarding	Reporting & Platform Management
Accept SDK (embedded in your app)	🟢 Required	🟡 Optional	🟡 Optional
Tapaya Terminal app only (intent/deeplink, no SDK)	⚪ Not needed	🟡 Optional	🟡 Optional
Reporting / back-office only	⚪ Not needed	⚪ Not needed	🟢 Required

Merchant Authentication: the SDK authenticates as a merchant using a login token your backend requests. Not needed for Tapaya Terminal integrations: the merchant signs in directly to the Tapaya Terminal app, so there's no SDK session for your backend to authenticate.
Merchant Onboarding: optional for both payment integrations: onboard via the SDK UI, the Tapaya Platform UI, or the API, depending on who should collect the merchant's data.
Reporting & Platform Management: optional for either payment integration if you build your own dashboards; required (and sufficient on its own) if you're only pulling reporting data with no payment integration of your own.

All rows still require Authentication with a Server Secret Token.

Environments

Tapaya Platform API supports the following environments:

Production: Hosted at https://api.tapaya.com. This environment uses real accounts and involves real funds. Do not use the production environment for testing.
Sandbox: Hosted at https://api.sandbox.tapaya.com. This environment allows you to test your integration without any movement of real funds. Learn more about testing in our Testing / Sandbox guide.

Environment routing

The Accept SDK automatically routes requests based on how it was initialized:

Sandbox (default): Connects to the Sandbox environment at https://api.sandbox.tapaya.com.
Production: Connects to the Production environment at https://api.tapaya.com.

Authentication

All API requests must be authenticated using your Server Secret Token. Pass it as-is in the Authorization header of your HTTP requests.

Authorization: REPLACE_ME

To authenticate your platform against the API, you must generate a Server Secret Token on the API Keys page and replace REPLACE_ME above with it.

Security Warning

Your Server Secret Token carries high privileges. Never expose it in client-side code (mobile apps, web browsers). It must only be used from your secure backend servers.

If a token is compromised, revoke it from the API Keys page; revocation takes effect immediately and cannot be undone. Generate a replacement token before or after revoking, as needed; there is no in-place "rotate" action, so update your backend configuration with the new token once it's created.

No key scoping

Every Server Secret Token carries the same organization-wide privileges; tokens cannot currently be scoped to specific endpoints or merchants. Treat any token as equivalent to full API access for your organization.

The server is only accessible through the HTTPS protocol, with TLS 1.2 or later enforced at the infrastructure level. Rate limiting is implemented (100 requests per minute per IP address); requests overloading the server will return a 429 Too Many Requests error.

Merchant Authentication (Accept SDK integrations)

Accept SDK integrations only

Skip this section if you're driving the Tapaya Terminal app directly (intent/deeplink, no embedded SDK); the signed-in Tapaya Terminal account is the merchant of record, and your backend never authenticates a merchant session. See Integrate without the SDK.

To allow your merchants to use the Tapaya Accept SDK, you must implement the following endpoints on your backend.

Register a New Merchant

Before a merchant can use the SDK, they must be registered in the Tapaya system. This is typically done when a user signs up for your service. You only need to register the merchant once. Registration can be done in Tapaya Platform UI or using the API.

Endpoint: POST /merchant/auth/register

curl -X 'POST' 'https://api.tapaya.com/merchant/auth/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: REPLACE_ME' \
-d '{
        "merchantToken": "unique_merchant_id_from_your_db",
        "merchantName": "Acme Corp",
        "email": "admin@acme.com"
    }'

Parameters:

Field	Type	Required	Description
`merchantToken`	`string`		A unique, stable identifier from your system (e.g., database ID) that identifies the merchant. If not provided, a random token is generated for you.
`merchantName`	`string`		Human-readable name to identify the merchant in dashboard and reports. Defaults to `merchantToken` if not provided.
`email`	`string`	✓	Admin email of the merchant, used for login and critical communication.

Responses:

Code	Description
`200`	Merchant successfully registered
`400`	Request validation error
`401`	Unauthorized
`409`	Conflict: merchant already registered

Response body:

{
    "merchantToken": "unique_merchant_id_from_your_db"
}

To allow a mobile device to initialize the SDK for a specific merchant, you must generate a short-lived login token. Your mobile app will request this from your backend, and your backend will request it from Tapaya. You need a fresh token every time the SDK is initialized.

Endpoint: POST /merchant/auth/login

curl -X 'POST' 'https://api.tapaya.com/merchant/auth/login' \
-H 'Content-Type: application/json' \
-H 'Authorization: REPLACE_ME' \
-d '{
        "merchantToken": "unique_merchant_id_from_your_db",
        "allowOnboarding": true,
        "employeeEmail": "john@acme.com"
    }'

Parameters:

Field	Type	Required	Description
`merchantToken`	`string`	✓	Integrator's merchant identifier for which the authentication token will be issued. Same as in `/auth/register`.
`allowOnboarding`	`boolean`		`true` if the user can access and update onboarding/KYB information, enroll new payment methods, and approve the T&C on behalf of the merchant. Must be `true` for the first call to enable the merchant to enroll at least one payment method. `false` if the user is denied access to onboarding and can only use already configured payment methods. Defaults to `true`.
`employeeEmail`	`string`		Email of the employee using the terminal.

Responses:

Code	Description
`200`	Merchant successfully logged in
`400`	Request validation error
`401`	Unauthorized
`404`	Not Found

Response body:

{
    "token": "EesrFq4PUK1WxHUj93hkrKASDFp8GxJ0"
}

Pass this token to your mobile app to initialize the SDK. Securely transport it to the mobile app and delete it immediately after usage. The token is bound to the merchant identified by merchantToken.

Security Warning

Ensure you use the correct merchantToken when retrieving the SDK token. The Tapaya SDK uses this token to log in on behalf of the merchant, granting access to their data and funds.

Merchant Onboarding

Applies regardless of payment integration

This section applies whether you embed the Accept SDK or drive the Tapaya Terminal app directly; use it if you want to create and manage merchants through the API instead of the Tapaya Platform UI. If your merchants already sign in and complete onboarding directly inside the Tapaya Terminal app, you can skip this section.

Registering a merchant (see Merchant Authentication above) creates its account, but the merchant cannot process live payments until onboarding is complete. Tapaya supports several onboarding experiences; all can be managed from the Tapaya Platform UI and automated where appropriate.

Flow	When to use it	API entry point
SDK UI	The merchant completes a guided flow inside your mobile app.	Retrieve an SDK token with `POST /merchant/auth/login`, then open the SDK onboarding flow.
Tapaya Platform UI	Your operations team completes onboarding on the merchant's behalf.	Register the merchant with `POST /merchant/auth/register`; no onboarding API call is required.
Your own UI	You collect and validate onboarding information in your product.	Validate sections with `POST /integrator/merchant/onboarding/validate/*`, then submit with `POST /integrator/merchant/onboarding`. Detailed below.
Email invite	A known merchant receives a single-use invitation to self-onboard.	Send an invite with `POST /integrator/merchant/send-registration-invite`; list or revoke it through `/integrator/merchant/invites`.
Campaign link	Multiple or not-yet-known merchants use a reusable self-registration link.	Create a link with `POST /integrator/merchant/reusable-registration-invites`; list or revoke links through the same resource.

For a detailed comparison of these flows, see the Merchant Onboarding guide.

Submit Onboarding through the API

If you want to collect onboarding information in your own product instead of sending merchants to the Tapaya Platform, submit it directly. Validate each section as the merchant fills it in with the validate/* endpoints below, then submit everything in one call, which creates the merchant and its onboarding profile together, and registers it with your organization's preferred payment processor.

Merchant not created on failure

POST /integrator/merchant/onboarding creates the merchant and submits onboarding in a single call. If the onboarding data is invalid, it returns 422 with field-level errors and no merchant is created; there is no partially-onboarded merchant to clean up or resume.

Validate Identity

Endpoint: POST /integrator/merchant/onboarding/validate/identity

curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding/validate/identity' \
-H 'Content-Type: application/json' \
-H 'Authorization: REPLACE_ME' \
-d '{
        "legalName": "Acme Corp s.r.o.",
        "businessTypeId": 2,
        "email": "admin@acme.com",
        "registrationNumber": "12345678",
        "vatNumber": "CZ12345678",
        "incorporationDate": "2018-04-01"
    }'

Parameters:

Field	Type	Required	Description
`legalName`	`string`	✓	Legal name of the business or individual account holder.
`businessTypeId`	`int`	✓	Type of business entity (`BusinessTypeEnum`).
`email`	`string`	✓	Contact email address.
`registrationNumber`	`string`	✓	Official business registration number. Checked for duplicates within your organization.
`vatNumber`	`string`		VAT registration number, if applicable.
`incorporationDate`	`date`		Date the business was legally incorporated (`YYYY-MM-DD`).

Response body:

{
    "valid": true,
    "errors": []
}

A registrationNumber already used by another merchant in your organization comes back as a valid: false error with code: "DUPLICATE_REGISTRATION_NUMBER" rather than a 409; this endpoint always returns 200.

Validate Address

Endpoint: POST /integrator/merchant/onboarding/validate/address

curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding/validate/address' \
-H 'Content-Type: application/json' \
-H 'Authorization: REPLACE_ME' \
-d '{
        "line1": "Wenceslas Square 1",
        "city": "Prague",
        "postalCode": "11000",
        "countryId": 1
    }'

Parameters:

Field	Type	Required	Description
`line1`	`string`	✓	First line of the street address.
`line2`	`string`		Second line of the street address, if applicable.
`city`	`string`	✓	City name.
`postalCode`	`string`	✓	Postal or ZIP code.
`state`	`string`		State or region, if applicable.
`countryId`	`int`	✓	Country (`CountryEnum`).

Response body: same {valid, errors} shape as Validate Identity.

Validate Business Profile

Endpoint: POST /integrator/merchant/onboarding/validate/business

curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding/validate/business' \
-H 'Content-Type: application/json' \
-H 'Authorization: REPLACE_ME' \
-d '{
        "mcc": "5411",
        "url": "https://acme.example.com",
        "supportPhone": "+420123456789",
        "statementDescriptor": "ACME CORP"
    }'

Parameters:

Field	Type	Required	Description
`mcc`	`string`	✓	Four-digit Merchant Category Code.
`url`	`string`		Business website URL. Either `url` or `productDescription` is required.
`productDescription`	`string`		Description of products or services. Either `url` or `productDescription` is required.
`supportPhone`	`string`	✓	Customer support phone number, in E.164 format.
`statementDescriptor`	`string`	✓	Text shown on customer bank statements (1–22 characters).
`averageItemValue`	`long`		Average transaction value, in minor currency units.
`expectedMonthlyTurnover`	`long`		Expected monthly revenue, in minor currency units.
`numberOfEmployees`	`int`		Number of employees at the business.
`annualTurnover`	`long`		Annual revenue, in minor currency units.
`balanceSheetTotal`	`long`		Total balance sheet value, in minor currency units.

Response body: same {valid, errors} shape as Validate Identity.

Validate KYB

Endpoint: POST /integrator/merchant/onboarding/validate/kyb

Provide exactly one of individual (sole trader / self-employed) or company. For a company, list every owner, director, and authorized signatory in people.

curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding/validate/kyb' \
-H 'Content-Type: application/json' \
-H 'Authorization: REPLACE_ME' \
-d '{
        "businessTypeId": 2,
        "bankAccount": {
            "iban": "CZ6508000000192000145399",
            "bic": "GIBACZPX",
            "currencyId": 1,
            "beneficiaryName": "Acme Corp s.r.o."
        },
        "company": {
            "name": "Acme Corp s.r.o.",
            "registrationNumber": "12345678",
            "people": [
                {
                    "email": "jane@acme.com",
                    "firstName": "Jane",
                    "lastName": "Doe",
                    "role": {
                        "isOwner": true,
                        "isAuthorizedSignatory": true
                    }
                }
            ]
        }
    }'

Parameters:

Field	Type	Description
`businessTypeId`	`int`	Type of business entity (`BusinessTypeEnum`); determines whether `individual` or `company` fields are required.
`bankAccount`	`object`	Payout bank account (account number/IBAN + BIC, currency, beneficiary and bank address).
`individual`	`object`	Individual owner details, for sole traders. Mutually exclusive with `company`.
`company`	`object`	Company details, including a `people` array of owners, directors, and authorized signatories. Mutually exclusive with `individual`.

Each person in people (and individual) carries role.isOwner / isDirector / isRepresentative / isAuthorizedSignatory flags, plus optional identity fields (dateOfBirth, nationalityCountryId, officialIdType/officialIdNumber, address, ownershipPercentage, verificationDocuments). A person entry must be either invite-only or fully detailed; partially filled people are rejected. There are two ways to submit a person:

Invite-only: submit just email and a role. The person receives an email with instructions to complete their own personal details and identity verification directly, including uploading their own ID document; you don't need to collect anything else for them, and no document upload is required on your side.
Fully detailed: submit all of the person's personal details (name, date of birth, official ID, address, etc.) yourself. In this case you must also upload an ID document for that person; this is required, not optional, for every fully-detailed person.

Regardless of how many people are invite-only vs. fully detailed, you must always upload the company's registration/incorporation document before the merchant can be submitted for KYC review.

Response body: same {valid, errors} shape as Validate Identity.

Create Merchant with Onboarding

Submits everything from the previous three steps in one call, creates the merchant, and registers it with your organization's preferred payment processor.

Endpoint: POST /integrator/merchant/onboarding

curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding' \
-H 'Content-Type: application/json' \
-H 'Authorization: REPLACE_ME' \
-d '{
        "name": "Acme Corp",
        "merchantToken": "unique_merchant_id_from_your_db",
        "identity": {
            "legalName": "Acme Corp s.r.o.",
            "businessTypeId": 2,
            "email": "admin@acme.com",
            "registrationNumber": "12345678",
            "vatNumber": "CZ12345678"
        },
        "address": {
            "line1": "Wenceslas Square 1",
            "city": "Prague",
            "postalCode": "11000",
            "countryId": 1
        },
        "business": {
            "mcc": "5411",
            "url": "https://acme.example.com",
            "supportPhone": "+420123456789",
            "statementDescriptor": "ACME CORP"
        },
        "kyb": {
            "bankAccount": {
                "iban": "CZ6508000000192000145399",
                "bic": "GIBACZPX",
                "currencyId": 1,
                "beneficiaryName": "Acme Corp s.r.o."
            },
            "company": {
                "people": [
                    {
                        "email": "jane@acme.com",
                        "firstName": "Jane",
                        "lastName": "Doe",
                        "role": {
                            "isOwner": true,
                            "isAuthorizedSignatory": true
                        }
                    }
                ]
            }
        }
    }'

Parameters:

Field	Type	Required	Description
`name`	`string`	✓	The name of the merchant.
`merchantToken`	`string`		A unique, stable identifier from your system. If not provided, a random token is generated.
`identity`	`object`	✓	Same shape as Validate Identity.
`address`	`object`	✓	Same shape as Validate Address.
`business`	`object`	✓	Same shape as Validate Business Profile.
`kyb`	`object`	✓	Same shape as Validate KYB.

Responses:

Code	Description
`201`	Merchant created and onboarding submitted
`422`	Onboarding data invalid, see `errors`; merchant is not created

Response body (201):

{
    "merchantId": "018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e",
    "merchantToken": "unique_merchant_id_from_your_db",
    "name": "Acme Corp",
    "email": "admin@acme.com",
    "processors": [
        {
            "processorId": 5,
            "registered": true,
            "onboardingUrl": null
        }
    ]
}

onboardingUrl is populated when the processor requires the merchant to complete an additional hosted onboarding flow (e.g. identity verification) before it can process live payments.

Response body (422):

{
    "errors": [
        {
            "step": "identity",
            "field": "registrationNumber",
            "message": "A merchant with this registration number is already onboarded under this integrator (merchantId: 018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e).",
            "code": "DUPLICATE_REGISTRATION_NUMBER"
        }
    ]
}

Upload a Person's ID Document

Required for every fully-detailed person in kyb.company.people / kyb.individual (see Validate KYB); invite-only people upload their own instead, via the emailed link.

Endpoint: POST /integrator/merchant/{merchantId}/document

Request body is multipart/form-data, not JSON.

curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/document' \
-H 'Authorization: REPLACE_ME' \
-F 'paymentProcessorId=5' \
-F 'documentType=2' \
-F 'relatedOfficialIdNumber=123456789' \
-F 'frontFile=@./jane-doe-id-front.jpg' \
-F 'backFile=@./jane-doe-id-back.jpg'

Parameters:

Field	Type	Required	Description
`paymentProcessorId`	`int`	✓	Always `5` (`Shift4`).
`documentType`	`int`	✓	Type of document (`DocumentTypeEnum`: `2` Id, `6` Passport, `3` Address, `5` BankStatement, `1` Other).
`frontFile`	`file`	✓	Front side of the document image.
`backFile`	`file`		Back side of the document image, if applicable.
`relatedOfficialIdNumber`	`string`	✓	The person's `officialIdNumber` from Validate KYB, so the processor can match this document to the right person.
`submitMerchant`	`boolean`		Leave unset/`false` here: a person's ID is not the final upload of the batch. Only set `true` on the company document upload once every person's document has been uploaded.

Response body (200):

{
    "frontFileId": "file_1NqtHo2eZvKYlo2CZPg8Xt5h",
    "backFileId": "file_1NqtHp2eZvKYlo2CRTg9Xm3k",
    "uploadedAt": "2026-07-17T12:00:00Z"
}

Upload the Company Document

Required exactly once per merchant. If person details were not filled in, the authorized signatory will be able to upload this using the link from the onboarding email and this endpoint does not need to be called.

Endpoint: POST /integrator/merchant/{merchantId}/document

Request body is multipart/form-data, not JSON.

curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/document' \
-H 'Authorization: REPLACE_ME' \
-F 'paymentProcessorId=5' \
-F 'documentType=4' \
-F 'frontFile=@./acme-corp-register-extract.pdf' \
-F 'submitMerchant=true'

Parameters:

Field	Type	Required	Description
`paymentProcessorId`	`int`	✓	Always `5` (`Shift4`).
`documentType`	`int`	✓	Always `4` (`Company`) for this step.
`frontFile`	`file`	✓	The company's registration/incorporation document.
`submitMerchant`	`boolean`		Set to `true` to trigger the processor's KYC review now that every required document has been uploaded. Defaults to `false`.

**Response body (200):

{
    "frontFileId": "file_1NqtHo2eZvKYlo2CZPg8Xt5h",
    "backFileId": "file_1NqtHp2eZvKYlo2CRTg9Xm3k",
    "uploadedAt": "2026-07-17T12:00:00Z"
}

Reporting & Platform Management

These endpoints provide programmatic access to data and settings that are also available in the Tapaya Platform dashboard. You can use them to build custom dashboards, automate workflows, or pull reporting data, regardless of whether you embed the Accept SDK or drive the Tapaya Terminal app directly. They are authenticated the same way, with your Server Secret Token.

List Merchants

List merchants registered under this organization.

Endpoint: GET /integrator/merchant

curl -X 'GET' 'https://api.tapaya.com/integrator/merchant' \
-H 'Authorization: REPLACE_ME'

Response body:

[
    {
        "merchantId": "018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e",
        "merchantToken": "unique_merchant_id_from_your_db",
        "name": "Acme Corp",
        "businessType": "sole_proprietorship",
        "city": "Prague",
        "country": "CZ",
        "onboarded": true,
        "isActive": true
    }
]

Retrieve Payment History

Get a list of the latest 50 payments across all merchants in your organization. This is useful for auditing transactions or building a "Super Admin" view.

No filtering or pagination

This endpoint always returns the latest 50 payments org-wide; it does not currently accept query parameters for merchant, status, date range, or pagination. Use the Retrieve Payment Details endpoint to look up a specific payment by ID.

Endpoint: GET /integrator/organization/payment

curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment' \
-H 'Authorization: REPLACE_ME'

Response body:

[
    {
        "paymentId": "018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f",
        "paymentToken": "pay_abc123",
        "paymentProcessorId": 1,
        "paymentMethodId": 1,
        "terminalId": "018f8f2a-5d3a-7e4c-9b3f-4a8c3d9e6f5a",
        "locationId": "018f8f2a-6e4b-7f5d-ac4a-5b9d4eaf7a6b",
        "requestedAmount": 1999,
        "requestedCurrencyId": 1,
        "settlementAmount": 1999,
        "settlementCurrencyId": 1,
        "statusId": 3,
        "instrumentLabel": "VISA •••• 4242",
        "instrumentIdentifier": "4242",
        "createdAt": "2026-07-15T12:00:00Z",
        "processedAt": "2026-07-15T12:00:03Z",
        "merchantId": "018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e",
        "merchantName": "Acme Corp"
    }
]

Aggregated Statistics

Get payment statistics aggregated across all merchants in your organization. This endpoint returns total volumes per currency.

Endpoint: GET /integrator/organization/payment/stats

curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment/stats' \
-H 'Authorization: REPLACE_ME'

Response body:

An array with one entry per currency your organization has processed payments in.

[
    {
        "currencyId": 1,
        "amount": 4582317
    }
]

Retrieve Payment Details

Get full details for a single payment, including its underlying transactions, charges, and any refunds. Scoped to your organization; payments belonging to another organization return 404.

Payment, transaction, and charge

A payment is the purchase request as a whole: one fixed amount for one payment method. It contains one or more transactions, each representing an attempt to move money through a processor. A transaction contains one or more charges, each a concrete settlement event against a specific instrument (card, wallet, bank account).

Most payments have exactly one transaction with one charge. A payment can have multiple transactions when a card-terminal tap is retried (each tap attempt is paired in as its own transaction). A transaction can have multiple charges for asynchronous payment methods like crypto or bank transfer, where the processor reports partial or repeated settlement events over time (e.g. an underpaid crypto invoice topped up by a second on-chain payment). Refunds reference the payment and charge directly; they are not nested under transactions.

Endpoint: GET /integrator/organization/payment/{paymentId}

curl -X 'GET' 'https://api.tapaya.com/integrator/organization/payment/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f' \
-H 'Authorization: REPLACE_ME'

Responses:

Code	Description
`200`	Payment found
`404`	Payment not found, or not owned by your organization

Response body:

{
    "paymentId": "018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f",
    "paymentToken": "pay_abc123",
    "paymentProcessorId": 1,
    "paymentMethodId": 1,
    "terminalId": "018f8f2a-5d3a-7e4c-9b3f-4a8c3d9e6f5a",
    "locationId": "018f8f2a-6e4b-7f5d-ac4a-5b9d4eaf7a6b",
    "requestedAmount": 1999,
    "requestedCurrencyId": 1,
    "settlementAmount": 1999,
    "settlementCurrencyId": 1,
    "referralFee": 30,
    "statusId": 3,
    "terminalName": "Front Counter",
    "locationName": "Acme Corp, Prague",
    "merchantId": "018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e",
    "merchantName": "Acme Corp",
    "createdAt": "2026-07-15T12:00:00Z",
    "processedAt": "2026-07-15T12:00:03Z",
    "transactions": [
        {
            "transactionId": "018f8f2a-7f5c-7a6e-bd5b-6cae5fb0879c",
            "statusId": 3,
            "referenceInfo": null,
            "fxRate": 1.0,
            "createdAt": "2026-07-15T12:00:00Z",
            "processedAt": "2026-07-15T12:00:03Z",
            "cancelledAt": null,
            "charges": [
                {
                    "chargeId": "018f8f2a-8a6d-7b7f-ce6c-7dbf6ac1980d",
                    "chargeToken": "charge_abc123",
                    "statusId": 3,
                    "instrumentLabel": "VISA •••• 4242",
                    "instrumentIdentifier": "4242",
                    "authorizationReference": "123456",
                    "requestedAmount": 1999,
                    "requestedCurrencyId": 1,
                    "settlementAmount": 1999,
                    "settlementCurrencyId": 1,
                    "fxRate": 1.0,
                    "createdAt": "2026-07-15T12:00:03Z"
                }
            ]
        }
    ],
    "refunds": []
}

Refund a Payment

Refund a payment, in full or in part. Omit amount to refund the entire remaining settled amount.

Endpoint: POST /integrator/organization/payment/{paymentId}/refund

curl -X 'POST' 'https://api.tapaya.com/integrator/organization/payment/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f/refund' \
-H 'Content-Type: application/json' \
-H 'Authorization: REPLACE_ME' \
-d '{
        "amount": 1999,
        "refundReasonId": 1
    }'

Parameters:

Field	Type	Required	Description
`amount`	`long`		Amount to refund, in minor currency units. Omit for a full refund of the remaining settled amount.
`refundReasonId`	`int`	✓	Reason for the refund (`RefundReasonEnum`).

Responses:

Code	Description
`200`	Refund initiated
`400`	Request validation error
`404`	Payment not found, or not owned by your organization
`409`	Payment cannot be refunded in its current state, or the requested amount exceeds what remains refundable

Response body:

{
    "refundId": "018f8f2a-9b7e-7c8a-df7d-8ecf7bd2a91e",
    "refundToken": "refund_abc123",
    "statusId": 1,
    "refundReasonId": 1,
    "requestedAmount": 1999,
    "requestedCurrencyId": 1,
    "settlementAmount": 1999,
    "settlementCurrencyId": 1,
    "fxRate": 1.0,
    "authorizationReference": null,
    "referralFeeRefund": null,
    "createdAt": "2026-07-15T12:05:00Z",
    "processedAt": null
}

Async settlement

referralFeeRefund and processedAt are populated asynchronously once the processor confirms the refund. They are always null in the immediate response; poll Retrieve Payment Details or Retrieve Payment History to observe the final state.

API Integration

Swagger Documentation

On this page