### Cash-In API Response Examples Source: https://docs.reflowpayments.com/docs/api-reference/cash-in Example responses for successful and error scenarios in the Cash-In API. A successful response for creating a QR code includes transaction details and the QR code. Error responses indicate issues like 'Transaction not found' or general bad requests. ```json { "transactionId": 49, "externalId": "0f809427-d48d-40f8-8a4d-73166933a8fe", "orderId": "your-order-id", "qrCode": "00020126840014br.gov.bcb.pix2562qrcode...", "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUgAAAOQAAADkCAYAAACIV4i..." } ``` ```json { "message": "Transaction not found" } ``` ```json { "message": "No active acquirer" } ``` -------------------------------- ### Get Account Balance using cURL Source: https://docs.reflowpayments.com/docs/api-reference/cash-out This cURL command shows how to fetch the current account balance. It requires an `Authorization` header with a valid access token. ```bash curl --location 'URL_API/transaction/get/balance' \ --header 'Authorization: YOUR_TOKEN_HERE' ``` -------------------------------- ### GET /transaction/get/balance - Consult Account Balance Source: https://docs.reflowpayments.com/docs/api-reference/cash-out This endpoint allows you to retrieve the current balance of your account. It requires an Authorization header with your access token. ```APIDOC ## GET /transaction/get/balance ### Description Retrieves the current balance of the account. ### Method GET ### Endpoint https://cashout.safepayments.cloud/transaction/get/balance ### Parameters #### Headers - **Authorization** (string) - Required - Access token for the API. ### Request Example ```bash curl --location 'https://cashout.safepayments.cloud/transaction/get/balance' \ --header 'Authorization: YOUR_TOKEN_HERE' ``` ### Response #### Success Response (200 OK) - **balance** (integer) - The current available balance. - **retention** (integer) - Amount currently in retention. - **toAnticipate** (integer) - Amount available for anticipation. - **finalBalance** (integer) - The final calculated balance. #### Response Example ```json { "balance": 2596878, "retention": 5339, "toAnticipate": 4990, "finalBalance": 2586549 } ``` ``` -------------------------------- ### Get Account Balance Response JSON Source: https://docs.reflowpayments.com/docs/api-reference/cash-out This JSON object contains the account balance information. It includes the total balance, retention amount, amount to anticipate, and the final balance. ```json { "balance": 2596878, "retention": 5339, "toAnticipate": 4990, "finalBalance": 2586549 } ``` -------------------------------- ### GET /transaction/get/by/id/{transactionId} and GET /transaction/get/by/orderId/{orderId} Source: https://docs.reflowpayments.com/docs/api-reference/cash-in Retrieves transaction details using either the transaction ID or the order ID. This allows you to check the status and details of a specific payment. ```APIDOC ## GET /transaction/get/by/id/{transactionId} ## GET /transaction/get/by/orderId/{orderId} ### Description Retrieves transaction details using either the transaction ID or the order ID. This allows you to check the status and details of a specific payment. ### Method GET ### Endpoint - `GET /transaction/get/by/id/{transactionId}` - `GET /transaction/get/by/orderId/{orderId}` ### Parameters #### Path Parameters - **transactionId** (integer) - Required - The ID of the transaction to retrieve - **orderId** (string) - Required - The order ID associated with the transaction #### Headers - **Authorization** (string) - Required - Access token for the API ### Request Example ```bash curl --location 'https://cashin.safepayments.cloud/transaction/get/by/id/9029' \ --header 'Authorization: YOUR_TOKEN_HERE' ``` ### Response #### Success Response (200) - **transactionId** (integer) - The unique identifier for the transaction - **orderId** (string) - Your order ID - **object** (string) - The type of object, e.g., "cashin" - **status** (string) - The current status of the transaction (e.g., "paid") - **method** (string) - The payment method used (e.g., "pix") - **value** (integer) - The transaction value in cents - **endToEndId** (string) - The end-to-end ID of the transaction - **processedAt** (string) - The timestamp when the transaction was processed #### Response Example ```json { "transactionId": 9029, "orderId": "your-order-id", "object": "cashin", "status": "paid", "method": "pix", "value": 2000, "endToEndId": "E60746948202509031314A23187b0bK8", "processedAt": "2025-09-03T10:14:18.768543" } ``` ### Error Handling #### Transaction not found (404) ```json { "message": "Transaction not found" } ``` #### General Errors (e.g., 400 Bad Request) ```json { "message": "No active acquirer" } ``` ``` -------------------------------- ### Get Transaction by ID or Order ID using cURL Source: https://docs.reflowpayments.com/docs/api-reference/cash-out These cURL commands demonstrate how to retrieve transaction details using either the `transactionId` or `orderId`. An `Authorization` header with a valid token is required. ```bash curl --location 'URL_API/transaction/get/by/id/6691' \ --header 'Authorization: YOUR_TOKEN_HERE' ``` ```bash curl --location 'URL_API/transaction/get/by/orderId/your-order-id' \ --header 'Authorization: YOUR_TOKEN_HERE' ``` -------------------------------- ### GET /transaction/get/by/orderId/{orderId} - Retrieve Transaction by Order ID Source: https://docs.reflowpayments.com/docs/api-reference/cash-out This endpoint allows you to retrieve a transaction using your custom order ID. You need to include an Authorization header with your access token. ```APIDOC ## GET /transaction/get/by/orderId/{orderId} ### Description Retrieves a transaction by your custom order ID. ### Method GET ### Endpoint https://cashout.safepayments.cloud/transaction/get/by/orderId/{orderId} ### Parameters #### Path Parameters - **orderId** (string) - Required - Your custom order ID for the transaction. #### Headers - **Authorization** (string) - Required - Access token for the API. ### Request Example ```bash curl --location 'https://cashout.safepayments.cloud/transaction/get/by/orderId/your-order-id' \ --header 'Authorization: YOUR_TOKEN_HERE' ``` ### Response #### Success Response (200 OK) - **transactionId** (integer) - The ID of the transaction. - **orderId** (string) - Your order ID. - **object** (string) - Type of transaction object (e.g., 'cashin'). - **status** (string) - The status of the transaction (e.g., 'paid'). - **method** (string) - The payment method used (e.g., 'pix'). - **value** (integer) - The transaction amount. - **endToEndId** (string) - The end-to-end ID of the transaction. - **processedAt** (string) - The timestamp when the transaction was processed. #### Response Example ```json { "transactionId": 6691, "orderId": "your-order-id", "object": "cashin", "status": "paid", "method": "pix", "value": 1000, "endToEndId": "E62746948202509031314A23187b0bK8", "processedAt": "2025-09-02T10:14:18.768543" } ``` ``` -------------------------------- ### GET /transaction/get/by/id/{transactionId} - Retrieve Transaction by ID Source: https://docs.reflowpayments.com/docs/api-reference/cash-out This endpoint allows you to retrieve a specific transaction using its unique transaction ID. You need to include an Authorization header with your access token. ```APIDOC ## GET /transaction/get/by/id/{transactionId} ### Description Retrieves a transaction by its ID. ### Method GET ### Endpoint https://cashout.safepayments.cloud/transaction/get/by/id/{transactionId} ### Parameters #### Path Parameters - **transactionId** (string) - Required - The ID of the transaction to retrieve. #### Headers - **Authorization** (string) - Required - Access token for the API. ### Request Example ```bash curl --location 'https://cashout.safepayments.cloud/transaction/get/by/id/6691' \ --header 'Authorization: YOUR_TOKEN_HERE' ``` ### Response #### Success Response (200 OK) - **transactionId** (integer) - The ID of the transaction. - **orderId** (string) - Your order ID. - **object** (string) - Type of transaction object (e.g., 'cashin'). - **status** (string) - The status of the transaction (e.g., 'paid'). - **method** (string) - The payment method used (e.g., 'pix'). - **value** (integer) - The transaction amount. - **endToEndId** (string) - The end-to-end ID of the transaction. - **processedAt** (string) - The timestamp when the transaction was processed. #### Response Example ```json { "transactionId": 6691, "orderId": "your-order-id", "object": "cashin", "status": "paid", "method": "pix", "value": 1000, "endToEndId": "E62746948202509031314A23187b0bK8", "processedAt": "2025-09-02T10:14:18.768543" } ``` ``` -------------------------------- ### Get Transaction Response JSON Source: https://docs.reflowpayments.com/docs/api-reference/cash-out This JSON object represents the successful response when retrieving a transaction. It includes details such as transaction ID, order ID, status, method, value, and processing time. ```json { "transactionId": 6691, "orderId": "your-order-id", "object": "cashin", "status": "paid", "method": "pix", "value": 1000, "endToEndId": "E62746948202509031314A23187b0bK8", "processedAt": "2025-09-02T10:14:18.768543" } ``` -------------------------------- ### Webhook Event Handling Source: https://docs.reflowpayments.com/docs/webhooks/overview Understand how Reflow Payments sends event notifications via HTTP requests and how to validate them. ```APIDOC ## Webhook Event Handling ### Description Events are sent via HTTP requests to your registered endpoint URL. These events can include a header for validation. All Cash-In and Cash-Out operations are confirmed via Webhook. Configure your webhook in the control panel under **Settings => Webhooks**. ### Method POST (typically, but depends on your registration) ### Endpoint Your registered webhook URL ### Parameters #### Query Parameters None specified. #### Request Body - **event_type** (string) - The type of event that occurred (e.g., 'payment.succeeded', 'payout.completed'). - **payload** (object) - Contains the details of the event. The structure varies based on the event type. ### Request Example ```json { "event_type": "payment.succeeded", "payload": { "transaction_id": "txn_12345abcde", "amount": 100.50, "currency": "USD", "status": "completed", "customer_id": "cust_67890fghij" } } ``` ### Response #### Success Response (200 OK) - **status** (string) - Acknowledgment of receipt, e.g., "received". #### Response Example ```json { "status": "received" } ``` #### Error Handling - **400 Bad Request**: If the request body is malformed or invalid. - **401 Unauthorized**: If validation fails (e.g., invalid signature header). - **500 Internal Server Error**: If there's an issue processing the event on your end. ``` -------------------------------- ### Create Pix QR Code for Cash-In Payment Source: https://docs.reflowpayments.com/docs/api-reference/cash-in This endpoint creates a Pix QR Code for receiving payments. It requires payer and product details, along with the transaction value. Optional parameters include postback URL, order ID, splits, and tracking parameters. The response contains transaction IDs and the QR Code in both string and Base64 formats. ```json { "payerName": "John Doe", "payerDocument": "12345678901", "payerEmail": "test@gmail.com", "payerPhone": "11999999999", "productName": "Cash-In Product", "productDescription": "Description of Cash-In Product", "value": 5000, "postbackUrl": "https://your-postback-url.com", "orderId": "your-order-id", "splits": [ { "clientId": "3fbfe257-adf0-4581-9169-7bf8e265f64f", "value": 500 } ], "trackingParameters": { "src": "...", "sck": "...", "utmSource": "...", "utmCampaign": "...", "utmMedium": "...", "utmContent": "...", "utmTerm": "..." } } ``` -------------------------------- ### POST /transaction/qrcode/cashin Source: https://docs.reflowpayments.com/docs/api-reference/cash-in Creates a Pix QR Code for a cash-in transaction. This endpoint is used to initiate a payment request where customers can pay using Pix via a generated QR code. ```APIDOC ## POST /transaction/qrcode/cashin ### Description Creates a Pix QR Code for a cash-in transaction. This endpoint is used to initiate a payment request where customers can pay using Pix via a generated QR code. ### Method POST ### Endpoint https://cashin.safepayments.cloud/transaction/qrcode/cashin ### Parameters #### Request Body - **payerName** (string) - Required - Name of the payer - **payerDocument** (string) - Required - Payer's identification document - **payerEmail** (string) - Required - Payer's email address - **payerPhone** (string) - Required - Payer's phone number - **productName** (string) - Required - Name of the product or service - **productDescription** (string) - Required - Description of the product or service - **value** (integer) - Required - Transaction value in cents - **postbackUrl** (string) - Optional - Callback URL after the transaction - **orderId** (string) - Optional - Your order ID - **splits** (array) - Optional - List of transaction splits - **trackingParameters** (object) - Optional - UTM tracking parameters ### Request Example ```json { "payerName": "John Doe", "payerDocument": "12345678901", "payerEmail": "test@gmail.com", "payerPhone": "11999999999", "productName": "Cash-In Product", "productDescription": "Description of Cash-In Product", "value": 5000, "postbackUrl": "https://your-postback-url.com", "orderId": "your-order-id", "splits": [ { "clientId": "3fbfe257-adf0-4581-9169-7bf8e265f64f", "value": 500 } ], "trackingParameters": { "src": "...", "sck": "...", "utmSource": "...", "utmCampaign": "...", "utmMedium": "...", "utmContent": "...", "utmTerm": "..." } } ``` ### Response #### Success Response (200) - **transactionId** (integer) - The unique identifier for the transaction - **externalId** (string) - An external identifier for the transaction - **orderId** (string) - Your order ID - **qrCode** (string) - The generated Pix QR Code in text format - **qrCodeBase64** (string) - The generated Pix QR Code in Base64 format #### Response Example ```json { "transactionId": 49, "externalId": "0f809427-d48d-40f8-8a4d-73166933a8fe", "orderId": "your-order-id", "qrCode": "00020126840014br.gov.bcb.pix2562qrcode...", "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUgAAAOQAAADkCAYAAACIV4i..." } ``` ``` -------------------------------- ### Create Cash-Out (Payout) Request JSON Source: https://docs.reflowpayments.com/docs/api-reference/cash-out This JSON object represents a request to create a cash-out transaction. It includes the value, Pix key details, recipient information, and an order ID. The `postbackUrl` is optional. ```json { "value": 15000, "pixKeyType": 1, "pixKey": "user@example.com", "cpfCnpj": "12345678901", "person": { "name": "FULANO DE TAL", "email": "fulanodetal@gmail.com", "phone": "5511987452145" }, "orderId": "your-order-id" } ``` -------------------------------- ### POST /transaction/cashout - Create Payout Source: https://docs.reflowpayments.com/docs/api-reference/cash-out This endpoint allows you to efficiently and securely transfer funds to Pix accounts. It requires details such as the amount, Pix key type and value, recipient's CPF/CNPJ, personal information, and an order ID. ```APIDOC ## POST /transaction/cashout ### Description Allows efficient and secure transfer of funds to Pix accounts. ### Method POST ### Endpoint https://cashout.safepayments.cloud/transaction/cashout ### Parameters #### Request Body - **value** (integer) - Required - Amount for withdrawal (in cents) - **pixKeyType** (integer) - Required - Type of PIX key (0: CPF, 1: CNPJ, 2: EMAIL, 3: TELEPHONE, 4: RANDOM_KEY) - **pixKey** (string) - Required - PIX key to send funds - **cpfCnpj** (string) - Required - CPF or CNPJ associated with the PIX key - **person** (object) - Required - Details of the person receiving the PIX - **person.name** (string) - Required - Person's name - **person.email** (string) - Required - Person's email - **person.phone** (string) - Required - Person's phone number - **orderId** (string) - Required - Your order ID - **postbackUrl** (string) - Optional - Return URL after the transaction ### Request Example ```json { "value": 15000, "pixKeyType": 1, "pixKey": "user@example.com", "cpfCnpj": "12345678901", "person": { "name": "FULANO DE TAL", "email": "fulanodetal@gmail.com", "phone": "5511987452145" }, "orderId": "your-order-id" } ``` ### Response #### Success Response (200 OK) - **transactionId** (integer) - The ID of the transaction. - **orderId** (string) - Your order ID. - **gross** (integer) - The gross amount of the transaction. - **tax** (string) - The tax amount. - **liquid** (string) - The net amount after tax. - **status** (string) - The status of the transaction (0: Pending, 1: Paid, 2: Failed, 3: Canceled, 4: Refunded). - **createdAt** (string) - The timestamp when the transaction was created. - **success** (string) - Indicates if the transaction was successful. - **description** (null) - Additional description, if any. #### Response Example ```json { "transactionId": 100, "orderId": "your-order-id", "gross": 15000, "tax": "30", "liquid": "14970", "status": "0", "createdAt": "2025-04-02T13:26:52.0365664Z", "success": "true", "description": null } ``` ``` -------------------------------- ### Error Handling Source: https://docs.reflowpayments.com/docs/api-reference/cash-out Information on how errors are handled, including transaction not found and general validation errors. ```APIDOC ## Error Handling ### Transaction Not Found When a requested transaction cannot be found, the API will return: ```json { "message": "Transaction not found" } ``` ### General Errors General errors, such as missing required fields or incorrect data formats, will result in corresponding HTTP status codes and informative error messages. #### Example Error Response ```json { "message": "Validation Failed - value is required" } ``` ``` -------------------------------- ### API Key Authentication Source: https://docs.reflowpayments.com/docs/getting-started/authentication This section details how to authenticate your requests to the Secure Payments API using an API Key. The API Key should be included in the 'Authorization' header of every HTTP request. ```APIDOC ## API Key Authentication ### Description To authenticate with the Secure Payments API, you need to include your API Key in the `Authorization` header of each HTTP request. You can generate your API Key from your dashboard under **Settings => API Credentials**. ### Method All HTTP requests ### Endpoint All API endpoints ### Parameters #### Request Headers - **Authorization** (string) - Required - The API key for authentication. Format: `Bearer YOUR_API_KEY_HERE` ### Request Example ``` { "Authorization": "Bearer YOUR_API_KEY_HERE" } ``` ### Response #### Error Response (401 Unauthorized) - **message** (string) - Description of the error, e.g., "Invalid token." #### Response Example ```json { "message": "Invalid token." } ``` ### Best Practices - Never expose your API key publicly. - Do not share your API key with unauthorized third parties. - If you suspect your API key has been compromised, generate a new one immediately and invalidate the old one. ``` -------------------------------- ### API Key Authentication Header Source: https://docs.reflowpayments.com/docs/getting-started/authentication This snippet demonstrates how to include your API Key in the Authorization header for HTTP requests to the Secure Payments API. Replace 'YOUR_API_KEY_HERE' with your actual API key. This is a standard method for API authentication. ```http Authorization: Bearer YOUR_API_KEY_HERE ``` -------------------------------- ### Error Response: General Validation Failed JSON Source: https://docs.reflowpayments.com/docs/api-reference/cash-out This JSON object illustrates a general validation error, such as missing required fields. The message provides specific details about the validation failure. ```json { "message": "Validation Failed - value is required" } ``` -------------------------------- ### Cash-Out (Payout) Success Response JSON Source: https://docs.reflowpayments.com/docs/api-reference/cash-out This JSON object details the successful response from a cash-out creation request. It includes transaction identifiers, amounts, status, and timestamps. The `success` field indicates the outcome. ```json { "transactionId": 100, "orderId": "your-order-id", "gross": 15000, "tax": "30", "liquid": "14970", "status": "0", "createdAt": "2025-04-02T13:26:52.0365664Z", "success": "true", "description": null } ``` -------------------------------- ### Cash-In: Create QR Code Payment Event Source: https://docs.reflowpayments.com/docs/webhooks/events This event is triggered when a QR code payment is created for a cash-in transaction. It includes details such as transaction ID, status, method, value, and order ID. No external dependencies are required to process this event. ```json { "transactionId": 1000, "object": "cashin", "status": "created", "method": "pix", "value": 500, "processedAt": "2025-04-02T13:26:52.0365664Z", "orderId": "test-123", "observation": null } ``` -------------------------------- ### Retrieve Transaction by ID or Order ID Source: https://docs.reflowpayments.com/docs/api-reference/cash-in This endpoint allows retrieving transaction details using either the transaction ID or the order ID. It requires an Authorization header with a valid token. The response includes transaction status, method, value, and timestamps. ```curl curl --location 'URL_API/transaction/get/by/id/9029' \ --header 'Authorization: YOUR_TOKEN_HERE' ``` -------------------------------- ### Error Response: Transaction Not Found JSON Source: https://docs.reflowpayments.com/docs/api-reference/cash-out This JSON structure represents an error response when a requested transaction cannot be found. It contains a simple message indicating the issue. ```json { "message": "Transaction not found" } ``` -------------------------------- ### Cash-Out: Create Payout Event Source: https://docs.reflowpayments.com/docs/webhooks/events This event is generated when a cash-out payout is initiated. It contains transaction details like ID, status, method, value, and order ID. The 'destinationBank' field will be null at this stage. ```json { "transactionId": 2000, "object": "transfer", "status": "created", "method": "pix", "value": 500, "processedAt": "2025-04-02T14:26:52.0365664Z", "destinationBank": null, "orderId": "test-123", "observation": null } ``` -------------------------------- ### Cash-In: Confirm QR Code Payment Event Source: https://docs.reflowpayments.com/docs/webhooks/events This event signifies the confirmation of a QR code payment for a cash-in transaction. It includes all details from the 'created' event, plus the end-to-end ID and payer information. This event confirms successful payment processing. ```json { "transactionId": 1000, "object": "cashin", "status": "paid", "method": "pix", "value": 500, "endToEndId": "E18236120202509231211s04b597fb3c", "processedAt": "2025-04-02T13:26:52.0365664Z", "payer": { "transactionId": 1000, "name": "Fulano de Tal da Silva", "documentId": "80683806556", "bankName": null, "bankCode": null, "bankIspb": "18236120" }, "orderId": "test-123", "observation": null } ``` -------------------------------- ### Invalid Token Error Response Source: https://docs.reflowpayments.com/docs/getting-started/authentication This JSON object represents a common error response when the API key provided is invalid or missing. The API will return a 401 Unauthorized status code along with this message, indicating an authentication failure. ```json { "message": "Invalid token." } ``` -------------------------------- ### Cash-Out: Confirm Payout Event Source: https://docs.reflowpayments.com/docs/webhooks/events This event confirms that a cash-out payout has been successfully processed. It includes the end-to-end ID and detailed information about the destination bank. This signifies the completion of the payout. ```json { "transactionId": 2000, "object": "transfer", "status": "paid", "method": "pix", "value": 500, "endToEndId": "E3571349120350923320635128eb360b", "processedAt": "2025-04-02T14:26:52.0365664Z", "destinationBank": { "name": "Fulano de Tal da Silva", "cpfCnpj": "80683806556", "email": null, "pixKey": "80683806556", "pixKeyType": "", "bank": null, "bankId": null, "ispb": null }, "orderId": "test-123", "observation": null } ``` -------------------------------- ### Transaction Refund Event Source: https://docs.reflowpayments.com/docs/webhooks/events This event indicates that a transaction has been refunded. It applies to both cash-in and cash-out objects and includes details about the transaction, the status 'refund', and optionally, the reason for the refund in the 'observation' field. ```json { "transactionId": 1000, "object": "cashin", "status": "refund", "method": "pix", "value": 500, "processedAt": "2025-04-02T13:26:52.0365664Z", "destinationBank": { "name": "Fulano de Tal da Silva", "cpfCnpj": "80683806556", "email": null, "pixKey": "80683806556", "pixKeyType": "", "bank": null, "bankId": null, "ispb": null }, "orderId": "test-123", "observation": "Motivo da infração" } ``` ```json { "transactionId": 1000, "object": "transfer", "status": "refund", "method": "pix", "value": 500, "processedAt": "2025-06-02T13:26:52.0365664Z", "orderId": "test-123", "observation": "Motivo do reembolso" } ``` -------------------------------- ### Transaction Infraction Event Source: https://docs.reflowpayments.com/docs/webhooks/events This event is triggered when a transaction is flagged for infraction. It includes the transaction details and sets the status to 'infraction'. The 'observation' field can provide the reason for the infraction. ```json { "transactionId": 1000, "object": "cashin", "status": "infraction", "method": "pix", "value": 500, "processedAt": "2025-06-02T13:26:52.0365664Z", "orderId": "test-123", "observation": "Motivo da infração" } ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.