lighthouse.dock.tech

Dock Lighthouse

Welcome to Dock Lighthouse! You'll find comprehensive guides and documentation to help you start working with our products as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

The Data API is a product developed to provide easy access to mass information requests (receipts of payments). The data is delivered in batches by requesting from a single API.

The following categories are liable for data extraction from the Data API:

  • BANKTRANSFEROUT: Data of the transfers performed by our Bank Transfers OUT API;
  • PAYMENTS: Data of payments realized by our Payments API;
  • P2P: Data of transfers performed by our P2P Transfer API;
  • RECHARGES: Data of mobile recharges done by our Recharges API;
  • TRANSPORTCARDS: Data of transport card recharges done by our Transport Cards API;
  • PURCHASES: Data of card purchases and withdrawals. This service is only available in the production (PRD) environment;
  • BANKTRANSFERIN: Data of the cash in transfers performed to payment accounts. Transfers according to the ISO 8583 are not included;
  • CASHIN_ISO8583: Data of the cash in transfers according to the ISO 8583 performed to payment accounts;
  • TEDIN_ALIAS: Data of the cash in transfers performed by Alias Motor;
  • TEDIN_PSTIS: Data of the cash in transfers performed by PSTIS Motor;
  • BILLET: Data of payment slips generated by our Billet API;
  • PAYMENTSLIP: Data of payment slips generated by our Payment Slip API.
  • PIX_TRANSFERS: Data of transfers and reversals performed by our Pix (FaaS) and Pix (BaaS) products.
  • VOUCHER: Data of voucher purchases performed by our Voucher API.

📘

Data Availability

For PURCHASES (Purchases and Withdrawals) service only, the data available will be up to D-1 (business days) at 12:00 PM (GMT-3).

Getting Started


In order to use our API service, it is required to configure an SFTP server in which the generated file will be available for download.

For such, you can request the creation of the SFTP server credentials by sending both an SSH public key (encrypted in RSA) and an email through the endpoint below. We will associate the public key with the SFTP server and share the SFTP access to your email.

POST datasetup.caradhras.io/v1/setup

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC+COeV+2RIx7l79iENIF+0OYNzAkt6+AWC3DLMd2c9okE+rahoE4XgCsWw30NgjD4ui2aNVKFzTW4BjZvMV79IEZBYkFsg7vjHHFygOLaHXqJfbbaDYYo4ida6IzbJHdgwhqT6R4KdYJBzosZDzpQ88zY54Ul26/gi48Q6q2ZZFwrrJOfwhwCQZQmjItapVAdU20h05asC5qsK6qRRHv6/+HMxhWuuwHirqGwmOV+Na8IZr9snCONUGqSbunM3iJhiFlOVdaOrtdUeYzu+rgBNCCU7iv9ZTRXcsMWwFladMUakhAL2n4OHWH5O6e/8AFv/mn1jF3XPdLaHYQemvLG4szAQWXv4CBiVEqBs7b71a1zpNsr89EoLdQZtnAyJ7u2nbffF3JnrKH70q3o1kojZJ22vMKEH375JqsjwyxP66NJP0QgG0YM2KRuVovpA1q/L7nVAuZR/1fuvxAU45HVvKdSRbL+koqyykuV2RLMo3i58PRg6TGSkWbA3+tT+Fn8=

Once the credentials are created, the "Information Security" team will send an email with the command to access the SFTP server where the data extraction files will be available for download. The example below presents the command to access the SFTP server, which contains the password (PRIVATEKEY), the user name (issuer_example), and the host (host.example).

sftp -i PRIVATEKEY [email protected]

🚧

Private Key

It is necessary to replace the word PRIVATEKEY with your SSH private key associated with the SSH public key shared.

If desired, you can check the status of your request through the endpoint below:

GET datasetup.caradhras.io/v1/setup

Step-by-Step


1) Request a data extraction ticket: After requesting the information, a ticket associated with the request is generated and the data extraction processes are started. This data will be made available in a .csv file and compressed according to the request (.zip or .gz).

GET data.caradhras.io/v1/transactions

📘

Account Receipts

It is possible to use the query string accountId to extract receipts for a specific account.

📘

Data Extraction Interval

It is possible to request data from D-1 (a day before the request), with a maximum range of 31 days (calendar days before the day requested).

2) Check the ticket status: It is necessary to check the ticket status to see when it changes from requested to finished, meaning that the file is available to download via SFTP in the host domain defined by our information security team.

GET data.caradhras.io/v1/transactions/{ticket}

File Nomenclature


The name of the file generated from the data extraction will follow the pattern below:

  • IDISSUER_SERVICE_YYYYMMDD_HHMMSS.csv.zip/gz

Where:

  • IDISSUER is the issuer identification code;
  • SERVICE is the service for which the data extraction was requested;
  • YYYYMMDD_HHMMSS is the timestamp of the file generation;
  • .csv is the data extraction file format;
  • .zip/gz is the compress format selected in the request (.zip or .gz)

Data Structure


All requested data is available in .csv format. The first line of the .csv file is the header and describes the fields related to the service in which the data was requested. The other lines bring the information of one transaction of receipt (the delimiter used to separate fields is comma).

The tables below present the name and description of each field returned by the services available in Data API.

BANKTRANSFEROUT

Field (database)

Description

Field Type

id

Transfer ID.

Integer

idAdjustment

Adjustment identification ID.

Integer

transactionCode

Code of the transaction.

String

idIssuer

Issuer identification code.

Integer

description

Banktransfer description.

String

idOriginAccount

ID of the origin account.

Integer

value

Transfer amount.

Number

typeAccountFavored

Beneficiary type. The types are "fisico" if natural person (NP) or "juridico" if legal person (LP).

String

nameFavored

Beneficiary name.

String

bankFavored

Beneficiary bank ID.

Integer

agencyFavored

Beneficiary agency number.

Integer

digitAgencyFavored

Beneficiary agency digit.

String

accountFavored

Beneficiary account number.

Integer

digitAccountFavored

Beneficiary account digit.

String

cnabFileName

CNAB file name.

String

statusTransfer

Transfer status.

String

tariffCode

Tariff code number.

String

transferenceDate

Date of the transfer.

String

transferSuccess

Is shows if the transfer was successful.

Boolean or NULL

codStatusTransfer

Transfer status code.

String

processDate

Processing date.

String

uid

Unique identification code of the transfer.

String

cpfCnpjFavored

Beneficiary document ("CPF" number or "CNPJ" number).

Integer

PAYMENTS

Field (database)

Description

Field Type

id

Receipt identification code.

Integer

idAccount

Payer account ID.

Integer

idAdjustment

Adjustment identification code.

Integer or NULL

idIssuer

Id from the issuer (10 digits).

Integer

barCodeNumber

Payment slip bar code number, also known as "linha digitável".

String

description

Payment slip description.

String

dueDate

Payment slip due date (ISO 8601 format).

String

fine

Payment slip fine. This value will not add to the “amount” field, which means that it’s simply informative to save the information about fine.

Number

assignor

Payment slip assignor.

String

transactionCode

Code from the payments transaction (it's generated even if the payment didn't happen).

String

transactionDate

Date when the transaction happened (ISO 8601 format).

String

status

Status of the Payment transaction.

String

idPaymentConfirmation

Id generated if the payment is concluded.

String or NULL

assignorDocument

Payment slip assignor document.

String(100)

discount

Payment slip discount. This value will not add to the “amount” field, which means that it’s simply informative to save the information about discount.

Number

interest

Payment slip interest rate (juros e mora).This value will not add to the “amount” field, which means that it’s simply informative to save the information about interest.

Number

amount

Payment slip amount.

Number

P2P

Field (database)

Description

Field Type

id

Receipt id.

Long

transactionCode

Unique identifier of the P2P transfer transaction.

String

originalAccount

The account ID of the Account that is the source of the P2P transfer transaction.

Long

destinationAccount

The account ID of the Account that will receive the P2P transfer transaction amount.

Long

amount

The amount of the transaction that will be transferred from “original_account” to the "destination_account".

BigDecimal

date

Date and time when the transaction happened ("yyyy-MM-ddTHH:mm:ss.sss" format).

String

description

Open field for inserting a description about the P2P transfer transaction.

String

idAdjustment

Adjustment identification code of the operation in the original account.

Long

idIssuer

Issuer identification code.

Long

tpAdjustment

P2P type.

Character

transactionTariffCode

Unique tariff code related to this transaction.

String

idAdjustmentDestination

Adjustment identification code of the operation in the destination account.

Long

RECHARGES

Field (database)

Description

Field Type

id

Recharge identification code.

Integer

accountId

Account identification code.

Integer

ddd

DDD number ("Discagem Direta à Distância" or "Direct Distance Dialing").

String

phoneNumber

Phone number.

String

dealerCode

Identification code of the mobile operator.

String

amount

Amount to recharge.

Integer

amountKey

Key of the specific amount used in the recharge.

Integer

idAdjustment

Identification code for debit transaction occurred.

Integer

orderId

Recharge order identification code.

String

transactionCode

Specific code of every recharge.

String

rechargeDate

Date that the recharge occurred (ISO 8601 format).

String

idIssuer

Identification code of the issuer.

Integer

TRANSPORTCARDS

Field (database)

Description

Field Type

id

Transport card identification code.

Integer

idDablam

SPTrans recharge identification code.

String

accountId

Account identification code.

Integer

idIssuer

Issuer identification code.

Integer

idAdjustment

Adjustment identification code.

Integer

cardNumber

SPTrans card number.

Integer

creditType

Identification code of the credit modality.

Integer

productCode

Identification code of the card's product.

Integer

value

Recharge amount.

Number

amount

Number of recharges executed in the card.

integer

transactionCode

DOCK's recharge identification code.

String

date

Recharge date (ISO 8601 format).

String

PURCHASES

Field (database)

Description

Field Type

id

Receipt identification code.

Long

issuer

Issuer name.

String

issuerId

Issuer identification code.

Long

purchaseEventId

Event identification code.

Long

accountId

Account identification code.

Long

cardId

Card code.

Long

authorizationId

Authorization identification number.

String

transactionId

Transaction identification number.

Long

authorizationCode

Authorization identification code.

String

acquiringCode

Acquiring identification code.

String

targetCurrencyCode

Target currency code of the transaction.

String

sourceCurrencyCode

Origin currency code of the transaction.

String

installment

Number of installments.

String

status

Transaction status. The status that can be returned are: "Baixada por prazo", "Cancelada", "Estornada", "Processada".

String

middle

Purchase origin.

String

operation

Operation identification.

String

merchant

Merchant description.

String

brandMerchant

External merchant description.

String

mcc

Merchandise commercial code.

String

purchaseAmount

Total purchase amount.

BigDecimal

sourceAmount

Total purchase amount in origin currency.

BigDecimal

targetAmount

Total purchase amount in the target currency.

BigDecimal

installmentAmount

Amount of each installment.

BigDecimal

firstInstallmentAmount

Amount of first purchase installment.

BigDecimal

contractAmount

Purchase amount with charges. It is always in BRL currency.

BigDecimal

tacAmount

TAC amount.

BigDecimal

iofAmount

IOF amount.

BigDecimal

commissionAmount

Issuer commission amount.

BigDecimal

prossesDate

Processing date (ISO 8601 format).

String

purchaseDate

Purchase date (ISO 8601 format).

String

BANKTRANSFERIN

Field (database)

Description

Field Type

id

Receipt identification code.

Long

adjustId

Adjustment identification code.

String

idAccount

Account identification code.

Long

idIssuer

Issuer identification code.

String

amount

Total transference amount.

Float

processDate

Processing date (ISO 8601 format).

LocalDateTime

CASHIN_ISO8583

Field (database)

Description

Field Type

id

Receipt identification code.

String

idIssuer

Issuer identification code.

Long

idAccount

Account identification code.

Long

amount

Transaction amount. (Always in BRL)

BigDecimal

createDate

Transaction receiving date. (ISO 8601 format)

LocalDateTime

processDate

Processing date. (ISO 8601 format)

LocalDateTime

transactionCode

Transaction identification code.

String

identification

Card number attached to idAccount addressed to cashin.

String

messageCode

ISO 8583 message code.

Allowed values: 0200 - Crédito, 0420 - Desfazimento

String

status

Transaction status. These status can be:

0 - Waiting processing;
1 - Process start;
2 - Success;
3 - Account does not exist;
4 - Card does not exist;
5 - Telephone does not exist;
6 - Queue exceptions;
7 - Another exception (Database);
8 - Another exception (Generic);
9 - Original transaction not found;
10 - Undo has already been done;
11 - Sum of the amount exceeds the daily limit;
12 - Amount greater than the original transaction;
15 - Person does not exist;
16 - Diverging documents.

String

authorizationCode

Authorization identification code.

String

TEDIN_ALIAS

Field (database)

Description

Field Type

id

Receipt identification code.

Long

amount

Total transference amount.

Float

beneficiaryBank

Beneficiary bank identification.

String

beneficiaryBranch

Beneficiary branch identification.

String

consignorBank

Consigor bank identification.

String

consignorBranch

Consignor branch identification.

String

description

Transfer Description.

String

idAccount

Account identification code.

Long

idAdjustmet

Adjustment identification code.

String

idIssuer

Issuer identification code.

Long

protocol

Protocol number.

String

transactionCode

Code of the transaction.

String

transactionDate

Date when the transaction happened (ISO 8601 format).

LocalDateTime

transactionStatus

Transaction status.

String

transactiontype

Transaction type.
Allowed Values: 21 - DOC, 31 - TED, 32 - TEF

String

TEDIN_PSTIS

Field (database)

Description

Field Type

id

Receipt identification code.

Long

idAccount

Account identification code.

Long

idIssuer

Issuer identification code.

Long

idAdjustment

Adjustment identification code.

String

beneficiaryAccount

Beneficiary account.

String

beneficiaryAccountType

Beneficiary account type.

String

beneficiaryBank

Beneficiary bank identification.

String

beneficiaryBankName

Beneficiary bank name.

String

beneficiaryBranch

Beneficiary branch identification.

String

beneficiaryDocument

Beneficiary document number.

String

beneficiaryDocumentType

Beneficiary document type.

String

beneficiaryIspb

Beneficiary ISPB.

String

beneficiaryName

Beneficiary name.

String

amount

Total transference amount.

Float

cashInDate

Beneficiary account cash in date. (ISO 8601 format)

LocalDateTime

consignorAccount

Consignor account number.

String

consignorAccountType

Consignor account type.

String

consignorBank

Consignor bank identification.

String

consignorBankName

Consignor bank name.

String

consignorBranch

Consignor branch identification.

String

consignorDocument

Consignor document number.

String

consignorDocumentType

Consignor document type.

String

consignorIspb

Consignor ISPB.

String

consignorName

Consignor name.

String

description

Transfer Description.

String

transactionCode

Code of the transaction.

String

transactionDate

Date when the transaction happened (ISO 8601 format).

LocalDateTime

BILLET

Field (database)

Description

Field Type

idBilletPier

Receipt identification code.

Long

idIssuer

Issuer identification code.

Long

idAccount

Account identification code.

String

amount

Total purchase amount.

Float

beneficiaryCode

Beneficiary identification code.

String

digitableLine

Billet digitable line.

String

documentNumber

Document number.

String

internalNumber

Internal number.

String

cep

Postal code.

String

payerAddress

Payer address.

String

payerName

Payer name.

String

payerTaxId

Payer tax identification.

String

receivedDate

Received billet date (ISO 8601 format).

String

processingDate

Processing date (ISO 8601 format).

String

paymentDate

Payment date (ISO 8601 format).

String

dueDate

Due date (ISO 8601 format).

String

registeredDate

Billet registration date (ISO 8601 format).

String

status

Billet status.

String

PAYMENTSLIP

Field (database)

Description

Field Type

documentNumber

Document identification number.

String

branch

Favored branch number.

Long

bank

Favored bank number.

Long

payerName

Payer name.

String

payerNeighborhood

Payment neighborhood.

String

payerCity

Payer city.

String

payerCep

Payer postal identification.

String

barCode

Billet bar code identification.

String

amount

Billet amount.

Float

consolidatedAmount

Total amount.

Float

documentDate

Document date (ISO 8601 format).

LocalDateTime

paymentDate

Payment date (ISO 8601 format).

LocalDateTime

discountDate

Discount date (ISO 8601 format).

LocalDateTime

closeDate

Close date (ISO 8601 format).

LocalDateTime

interestDate

Interest date (ISO 8601 format).

LocalDateTime

fineDate

Fine date (ISO 8601 format).

LocalDateTime

dueDate

Due date (ISO 8601 format).

LocalDateTime

deadlineAutomaticCancelation

Number of days to cancel billet automatically.

String

typeAutomaticCancelation

Type of automatic cancelation.

String

beneficiaryDocument

Beneficiary document number.

String

cobeneficiaryDocument

Cobeneficiary docuemnt number.

String

typeTitle

Payment Slip title type.

String

accountId

Account identification code.

Long

issuerId

Issuer identification code.

Long

digitableLine

Billet digitable line.

String

beneficiaryName

Beneficiary name.

String

subbeneficiaryName

Subbeneficiary name.

String

cobeneficiaryName

Cobeneficiary name.

String

paymentMethod

Payment method.

String

type

Payment slip type, which can be "Duplicata Mercantil" or "Duplicata de Serviço" (01 = "Duplicata Mercantil"; 02 = "Duplicata de Serviço").

String

typeContestation

Payment slip type contestation, also known as days left for "Protesto de Título" (01 = Has contestation; 02 = Doesn't have contestation).

String

status

Billet status.

String

billetType

Billet type.

String

subBeneficiayType

Sub Beneficiary type.

String

PIX_TRANSFERS

Field (database)

Description

Field Type

id

Transaction identification code.

Long

accountId

Account identification for the owner of DICT key.

Long

issuerId

Issuer identification code.

Long

adjustmentId

Adjustment identification code.

Long

amount

Transaction amount (always in BRL).

Float

correlationId

PIX transaction unique identifier generated by partner.

String

endToEndId

End-to-end payment identifier associated with the request. Used for rate-limiting.

String

payeeId

Payee identification code.

Long

payerAswer

Open field, partner insert information.

String

payerId

Payer identification code.

String

schedulingDate

PIX send date to SPI. This date will be used for scheduling (a function provided by BACEN in 2021) (ISO 8601 format).

String

transactionCode

Transaction code.

String

transactionDate

Transaction date (ISO 8601 format).

String

transactionStatus

Transaction status (EXECUTED, NOT_EXECUTED, PENDING or REVERSAL_EXECUTED).

String

transactionType

Transaction type (TRANSFER_DEBIT or TRANSFER_CREDIT).

String

transactionUuid

Non-mandatory idempotency key generated by the partner.

String

transferId

Transaction identification code.

Long

txId

Identifier for reconciliation of the recipient in cases of transfer originated by QR Code.

String

returnEndToEndId

End-to-end identifier of the return generated by the API after the confirmation of the return request. If the field is empty, it will be filled out later in the database. This field is returned as null if the transaction is not a reversal.

String

reversalCode

Identifying code of the reason for the return. Not null only for reversals. These codes can be:
0 - Duplicate payment order;
1 - Return due to the amount received not being in accordance with the expected;
2 - Return due to a PSP error;
3 - Return after technical problems, resulting in an incorrect transaction.

String

reversalReason

Open field for a description of the reason for the return. This field is returned as null if the transaction is not a reversal.

String

reversalStatus

Reversal status (REVERSAL_EXECUTED, NOT_EXECUTED or PENDING). This field is returned as null if the transaction is not a reversal.

String

reversalType

Reversal type (REVERSAL_DEBIT or REVERSAL_CREDIT). This field is returned as null if the transaction is not a reversal.

String

tarrifAmount

Pix tariff amount (always in BRL).

Float

type

Payment method used for transaction (0 - Manual; 1 - By key; 2 - static QRcode; 3 - dynamic QRcode).

String

updateDate

Last transaction update.

String

VOUCHER

Field (database)

Description

Field Type

id

Transaction identification code.

Long

idAccount

Account identification code.

Long

idIssuer

Issuer identification code.

Long

idAdjustment

Adjustment identification code.

Long

amount

Transaction amount.

BigDecimal

documentNumber

Individual national registration ID.

String

email

Individual e-mail.

String

description

Message that can be tracked by the user.

String

merchantId

Identification code of specific merchant.

String

orderId

Voucher request order identification code.

String

requestId

Unique identification for requisition tracking.

String

transactionCode

Code for the transaction of voucher requisition.

String

voucherCode

Code provided only after the transaction is completed.

String

transactionStatus

Transaction status (Allowed values: CONFIRMED or PENDING).

String

transactionDate

Transaction date (ISO 8601 format).

LocalDateTime

Updated about a month ago


Data API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.