post
https://api.adopay.com.br/v2/finance/create-copy-and-paste-transfer
This API processes a PIX payment using a QR Code in "copia e cola" (copy and paste) format via machine credentials (API audience). It decodes the QR Code, validates the payment details, creates and auto-approves the transaction. Authentication is done via Bearer token + HMAC signature.
Headers
| Parameter | Type | Description | Example |
|---|---|---|---|
| Authorization | String | Bearer + Access_token | Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo |
| hmac | String | HMAC (Hash-based Message Authentication Code) is an authentication algorithm that combines a private key with a message to create a Message Authentication Code (MAC). Computed from the full request body JSON. | hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b99f4081ff231b87f82118c1e77a959e1f40eacf690a8fa61a827a9ba01d546f6 |
Body Details
{
"source_account_branch_identifier": "0001",
"source_account_number": "123456",
"pix_copy_and_paste": "00020126580014br.gov.bcb.pix0136a629532e-7693-4846-852d-1bbff6b2f8cd520400005303986540510.005802BR5913Fulano de Tal6008BRASILIA62070503***63041D3D",
"amount": 100.50,
"tag": "Order #12345"
}
| Field | Type | Description | Required or Optional |
|---|---|---|---|
| source_account_branch_identifier | String | Branch identifier (agency number) of the source account from which the payment will be made. | required |
| source_account_number | String | Account number of the source account from which the payment will be made. | required |
| pix_copy_and_paste | String | PIX QR Code content in "copia e cola" format. The complete EMV string. Must have at least 1 character. | required |
| amount | Decimal | Payment amount. Must be greater than 0. Format: 2 decimal places (e.g., 100.50). | required |
| tag | String | Optional custom tag or reference for the payment. Can be used for invoice numbers, order IDs, or any custom reference. | optional |
Request Examples
Pay static QR Code:
POST /v2/finance/create-copy-and-paste-transfer
Authorization: Bearer <access_token>
hmac: <computed_hmac>
Content-Type: application/json
{
"source_account_branch_identifier": "0001",
"source_account_number": "123456",
"pix_copy_and_paste": "00020126580014br.gov.bcb.pix0136a629532e-7693-4846-852d-1bbff6b2f8cd520400005303986540510.005802BR5913Fulano de Tal6008BRASILIA62070503***63041D3D",
"amount": 50.00
}
Pay with tag reference:
POST /v2/finance/create-copy-and-paste-transfer
Authorization: Bearer <access_token>
hmac: <computed_hmac>
Content-Type: application/json
{
"source_account_branch_identifier": "0001",
"source_account_number": "654321",
"pix_copy_and_paste": "00020126580014br.gov.bcb.pix01361234567890123456789012345678901234520400005303986540550.005802BR5925Example Company Name6014CIDADE EXEMPLO62070503***63045ABC",
"amount": 250.00,
"tag": "Invoice #INV-2024-456"
}
Pay dynamic QR Code:
POST /v2/finance/create-copy-and-paste-transfer
Authorization: Bearer <access_token>
hmac: <computed_hmac>
Content-Type: application/json
{
"source_account_branch_identifier": "0001",
"source_account_number": "123456",
"pix_copy_and_paste": "00020126360014br.gov.bcb.pix0114+55119876543215204000053039865802BR5913Maria da Silva6008SAO PAULO622905251234567890123456789063040D3A",
"amount": 1000.00,
"tag": "Payment ref ABC-123"
}
Response Details
{
"worked": true,
"id": 54321,
"transaction_id": 54321,
"code_transaction": "xyz789-abc-123-def-456-ghi-789",
"status": "PROCESSING",
"amount": 100.50,
"fee": 0.00,
"key": null,
"tag": "Order #12345",
"from_accout": "123456-7",
"recipient_instution": "60701190",
"recipient_instution_name": "Banco Itaú S.A.",
"recipient_account_id": "098765",
"recipient_branch_id": "0001",
"recipient_legal_id": "12345678900",
"recipient_name": "João da Silva",
"recipient_account_type": "1",
"operationUuid": null,
"erro_descriptor": null,
"new_erro_descriptor": null
}
| Field | Type | Description |
|---|---|---|
| worked | Boolean | Always true for successful requests. |
| id | Integer | Transaction ID. |
| transaction_id | Integer | Same as id. Transaction ID. |
| code_transaction | String | Transaction UUID code. Unique identifier. |
| status | String | Transaction status. See TransactionStatusEnum values below. |
| amount | Float | Payment amount. |
| fee | Float | Transaction fee. Usually 0.00 for PIX. |
| key | String | PIX key. null for QR Code payments (key is embedded in pix_copy_and_paste). |
| tag | String | Custom tag/reference provided in the request. null if not provided. |
| from_accout | String | Source account number. (Note: field name contains a known typo preserved for backward compatibility.) |
| recipient_instution | String | Recipient bank ISPB code (extracted from QR Code). (Note: field name contains a known typo preserved for backward compatibility.) |
| recipient_instution_name | String | Recipient bank name (resolved from ISPB). null if not resolved. |
| recipient_account_id | String | Recipient account number (extracted from QR Code). null if not available. |
| recipient_branch_id | String | Recipient branch/agency number (extracted from QR Code). null if not available. |
| recipient_legal_id | String | Recipient CPF or CNPJ (extracted from QR Code). null if not available. |
| recipient_name | String | Recipient name (extracted from QR Code). null if not available. |
| recipient_account_type | String | Recipient account type. null if not available. |
| operationUuid | String | Bank operation UUID. null initially, filled after bank processing. |
| erro_descriptor | String | Error description if transaction fails. null if successful. |
| new_erro_descriptor | String | Updated error description. null if successful. |
Enum: TransactionStatusEnum
| Value | Description |
|---|---|
| NEW | Transaction created but not yet processed |
| PROCESSING | Transaction is being processed by the bank |
| APPROVED | Transaction approved and waiting for execution |
| SUCCESS | Transaction completed successfully |
| CANCELED / CANCELLED | Transaction canceled |
| ERROR | Transaction failed with error |
| AWAITING_BANK_CONFIRMATION | Waiting for bank confirmation |
| WAITING_REPROCESSING | Transaction is waiting to be reprocessed |
| PENDENT | Transaction pending |
Error Responses
| HTTP Code | Error Message | Description |
|---|---|---|
| 400 | Company not found | The company associated with the authenticated token was not found in the system. Verify your authentication token. |
| 400 | Account not found | The specified account does not exist, does not belong to your company, or your user does not have an active policy for it. |
| 400 | Account blocked for cashout | The source account has cashout operations blocked. Contact support if you believe this is an error. |
| 400 | Invalid QR Code | The PIX copy and paste string is malformed or invalid. Verify the content of the pix_copy_and_paste field. |
| 400 | QR Code expired | The QR Code has expired and cannot be used for payment. |
| 400 | Amount mismatch | The amount provided does not match the QR Code amount (for dynamic QR Codes with fixed amounts). |
| 401 | Unauthorized | Invalid or missing authentication token. Ensure you are sending a valid Bearer token and HMAC signature. |
| 422 | Validation error | Request validation failed. Check that all required fields are present and in the correct format. |
Business Rules
Account Validation:
- Source account must exist and belong to the authenticated
- Account must not have cashout operations blocked
QR Code Processing:
- QR Code is decoded to extract recipient information
- System validates QR Code format and structure
- Extracts: recipient name, document (CPF/CNPJ), bank ISPB, account details, amount
- QR Code must be valid and not expired
Amount Handling:
- For static QR Codes: User can specify any amount if the QR Code amount is 0 or editable
- For dynamic QR Codes: Amount must match the QR Code predefined amount
- Amount must be greater than 0
- Format: exactly 2 decimal places