Respawn PayDocs

Sandbox (Testing)

Test environment with no real money. It uses the same routes, headers and responses as production, with its own credentials and balance.

Base URL

Base URL
https://api.respawnpay.com/sandbox/api

In production the routes start with /api. In the sandbox, replace that /api with /sandbox/api and keep the rest of the path.

Examples
POST https://api.respawnpay.com/sandbox/api/v1/transactions/create
GET  https://api.respawnpay.com/sandbox/api/Balance/balance/{companyId}?currency=BRL
POST https://api.respawnpay.com/sandbox/api/Withdraw/request

Sandbox Credentials

The sandbox has its own credentials, with an initial balance of R$ 1,000.00. Both values start with sbx_ and do not work in production (and production credentials do not work in the sandbox). The sandbox companyId is the same as your production companyId.

X-Client-Id
string

sbx_..., unique to your company (different from production)

X-API-Key
string

sbx_..., shown only once

Creating and Managing Your Sandbox Account

The sandbox account is created from your production company, with the same fees. These routes use your dashboard login (header Authorization: Bearer plus X-Company-Id with your company ID), not the API key. Get the Bearer token from POST /api/Auth/login.

GET /api/v1/company/sandbox
GET

Shows whether the account exists, the clientId, the masked API key, the balance (reais), the webhook URL and counters

POST /api/v1/company/sandbox/activate
POST

Creates the test account: R$ 1,000.00 balance, clientId and apiKey (the apiKey is returned only in this response)

POST /api/v1/company/sandbox/rotate-key
POST

Generates a new apiKey; the previous one stops working immediately

POST /api/v1/company/sandbox/topup
POST

Resets the test balance to R$ 1,000.00

PUT /api/v1/company/sandbox/webhook
PUT

Body { "url": "https://...", "secret": "optional" }. Registers the test webhook for all event types; an empty url removes it

cURL
TOKEN=$(curl -s -X POST https://api.respawnpay.com/api/Auth/login \
  -H "Content-Type: application/json" \
  -d '{"usernameOrEmail":"<EMAIL>","password":"<PASSWORD>"}' | jq -r '.token')
curl -X POST https://api.respawnpay.com/api/v1/company/sandbox/activate \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Company-Id: <COMPANY_ID>"

Simulating a Payment

The sandbox QR Code has a valid format, but no bank can pay it. To change a charge's status, use the routes below, with the same headers and the transactionId returned on creation.

POST/sandbox/api/v1/sandbox/transactions/{transactionId}/pay
/pay
POST

Marks it as paid: credits the amount minus fees and sends the successful webhook

/fail
POST

Marks it as failed (expired or canceled): nothing is credited and the failure webhook is sent

/refund
POST

Refunds a paid charge: debits the gross amount, the fee is not returned, and the refunded webhook is sent

If the charge is not in the right state (for example, paying twice), the response is 409.

Response 200 (/pay)
{
  "id": "fde53161-6f37-409d-9448-b841fd4cc033",
  "status": "PAID",
  "amount": 1500,
  "fees": 0.0000,
  "balance": 1015.0000,
  "webhook": "successful",
  "message": "PIX pago (simulação). Saldo creditado e webhook enviado."
}

In this response, amount is in cents and balance and fees are in reais.

GET/sandbox/api/v1/sandbox/me

Confirms you are in the sandbox and shows the test balance (in reais).

Withdrawals in the Sandbox

The withdrawal comes out of the test balance and is paid immediately, with the successful webhook. An amount ending in ,99 (for example amount 1099) is refused on purpose: the amount returns to the balance and the failure webhook is sent. Use it to test how you handle a refused withdrawal.

Webhooks in the Sandbox

Sandbox webhooks have the same format as production. The test URL must be https, on port 443 and on a public domain. Register it with PUT /api/v1/company/sandbox/webhook (above), or with the same POST /sandbox/api/SendWebhook call used in production, authenticated with your sandbox X-Client-Id and X-API-Key. A URL that does not answer 2xx is retried up to 3 times, like in production.