Skip to main content

Batch payment transfer

This API aims to provide a standardized structure for receiving payment transfer orders. The orders go through validations from the initial order creation step to final approval, at which point a file is generated containing the outcome of all the orders in the request.

Input File​

Payment transfer orders must always be contained in a .csv file standardized according to the model provided. This is the file that is sent to the credit reconciliation API, validated, processed, and only then is the return file generated.

Return File​

This is the file made available to the partner at the end of all processing of a valid input file. It contains all the payment transfer orders that were approved and rejected.

Uploading the Input File​

To upload the input file, you first need to generate a temporary S3 (AWS) presigned link, which is used to upload any file to the BTG Empresas platform.

// example response:
{
  "upload_url": "https://btg-file-uploads.s3.amazonaws.com/user_28771ABC/8bce6cfc-dcd4-473b-9fae-60ef3f60ec11?AWSAccessKeyId=JAIAIR3IFH6UCHKS&SB\\u0026Expires=1447353431\\u0026Signature=abK2ncbdlAIl2hk2921AKHQ%",
  "file_url": "https://s3-sa-east-1.amazonaws.com/btg-file-uploads/8bce6cfc-dcd4-473b-9fae-60ef3f60ec11"
}

The upload_url field provides the route address to be used to upload the file, while the file_url field provides the file address to be used when creating the request in the Credit Reconciliation API.

After the file is uploaded, it remains available on our platform for up to 3 calendar days, until it is linked to an operation. If the file's expiration period is reached and the link has not been made, you will need to generate a new upload link and send the file again.

Create Request​

This Credit Reconciliation request creation step is where file validation and processing actually start, enabling you to look up the request's status afterward, either via a REST request or via Webhook.

  • Create Credit Reconciliation Request
// example response:
{
    "id": "0524b1ed-6a78-4f00-8394-543ffcd188f0",
    "status": "QUEUED"
}

Request status callback​

This is a route the partner must expose to receive information about a request's progress and also to receive the return file.

// example request:
{
    "id": "bb9d844c-8041-464c-b160-471d437231d6",
    "status": "QUEUED",
    "conciliatedFileS3Url": ""
}

Look up request status​

An alternative to using the webhook to look up the request status.

  • Look up request status ref:get_v1-credit-conciliation-agreementid-creditconciliationorderid
// example response:
{
    "id": "bb9d844c-8041-464c-b160-471d437231d6",
    "status": "QUEUED",
    "conciliatedFileS3Url": ""
}

Available Resources​

The Batch Payment Transfer API resources are available in the API Reference.

📘 API Reference

Batch payment transfer