WEpayments' Payin API (1.2)

Download OpenAPI specification:Download

Here you will find instructions on how to create a complete billing experience with WEpayments' Payin.

Use this API to generate a billing request used to make a single simple charge, using PIX, boleto, and credit card payment methods. Additionally, it is possible to create billing requests with splits between sellers.

With the integration of WEpayments' Payin, you will receive notifications for each payment. You can check the created charges, perform real-time reconciliation via webhook, cancel charges, request refunds, among other functionalities.

Authentication

bearerAuth

Security Scheme Type	HTTP
HTTP Authorization Scheme	bearer

Charge

Create a new QR Code Pix payment charge.

Generate a new QR Code Pix payment request. This also brings a copy-and-paste code, that ables the customer to pay either scanning the QR Code, or with the copy-and-paste code the client will pay in the internet banking app.

About callback notification

PIX is a fast way to pay, where you get notified of payments in less than a minute after the transaction is done or its status changes.

Possible charge status PIX

status_code	status	explanation
`1`	CREATED	The first status when the Pix is created.
`2`	CANCELED	Pix canceled due to expiration.
`7`	REJECTED	Pix rejected due to compliance reasons.
`3`	PAID	Pix successfully paid.
`4`	CREDITED	The amount is paid and available for withdrawal.
`5`	DROP_REQUESTED	PIX transaction canceled at the user's request.

Payment page

We offer a payment page that displays the Pix QR Code, allowing users to access and view payment instructions for the charge. For security reasons, it is not possible to open the payment page within an iframe.

Environment	URL
Sandbox	`https://pagar.sandbox.goboleto.com/?hash={key}`
Production	`https://pagar.goboleto.com/?hash={key}`

Authorizations:

bearerAuth

Request Body schema: application/json

callbackUrl	string <url> The url where we will submit the callbacks.
customNumber	string <= 255 characters Your identification number, it must be unique on our database.
clientId	integer or null <int32> ClientId of the account creating Pix. The custom number will be different for sandbox and production environment. Is mandatory if there is more than one account under your umbrella (sellers).
required	object Payment instructions.
required	object The person that you are charging object.
	object Fine when the expiration date is reached.
	object Schedule a discount for early payment, before the due date.
refundMode	string Default: "FULL_REFUND_CLIENT" Enum: "FULL_REFUND_CLIENT" "FULL_REFUND_RECIPIENT" "REFUND_BY_SPLIT" FULL_REFUND_CLIENT: The refund amount will be fully debited from the wallet of the issuer of the charge. FULL_REFUND_RECIPIENT: The refund amount will be fully debited from the seller informed in the split. Only be allowed if you have a maximum of 1 split participant. REFUND_BY_SPLIT: Allows you to indicate at the time of the refund of which wallets will be debited the amount of the refund.
	Array of objects[ items ] Splits are avaiable if you want to credit more than one wallet with the charged paid amount.
	object Use this object to inform the legal name of the final beneficiary, it could be your company's name or the company you are proving a service for. Final Beneficiary is a person or a company that will receive the amount paid .
	Array of objects (RegisteredAccounts) [ items ] Registered accounts that are authorized to make the payment, if the QRCode payment is made through an account not present on this list, an automatic refund will be made.

Responses

code	description en	description pt-br
restriction_receita	Rejected due to document restriction	Rejeitado devido a restrição de documento
restriction_underage	Rejected due to document restriction underage Brazilian law	Rejeitado devido a restrição de documento menor de idade pela lei brasileira
restriction_deceased_holder	Rejected due to document restriction deceased holder	Rejeitado devido a restrição documento de falecido
restriction_canceled	Rejected due to document restriction canceled document	Rejeitado devido a restrição documento cancelado
restriction_unknown	Rejected due to document restriction unknown document	Rejeitado devido a restrição documento não encontrado na Receita Federal
restriction_pending_regularization	Rejected due to document restriction pending of regularization	Rejeitado devido a restrição documento pendente de regularização
restriction_suspended	Rejected due to document restriction suspended	Rejeitado devido a restrição documento suspenso
restriction_partners_and_ownership	Rejected due to document restriction partners and ownership	Rejeitado devido a restrição documento de sócios e titularidades
restriction_judicial_block	Rejected due to document restriction judicial block	Rejeitado devido a restrição documento bloqueio judicial
restriction_cpf_irregular	Rejected due to document restriction	Rejeitado devido a restrição de documento
restriction_list_restrict	Rejected due to document restriction	Rejeitado devido a restrição de documento
restriction_pep	Rejected due to document restriction PEP (Politically Exposed Person)	Rejeitado devido a restrição de documento PEP (Pessoa politicamente exposta)
restriction_age_above_limit	Rejected due to restriction age as per compliance policy	Rejeitado devido a restrição de idade conforme política de conformidade
restriction_ofac	Rejected due to document restriction on OFAC list	Rejeitado devido a restrição de documento na lista OFAC
restriction_interpol	Rejected due to document restriction on INTERPOL list	Rejeitado devido a restrição de documento na lista da INTERPOL
restriction_onu	Rejected due to document restriction on ONU list	Rejeitado devido a restrição de documento na lista da ONU
restriction_euro	Rejected due to document restriction on EURO list	Rejeitado devido a restrição de documento na lista da EURO

code	description en	description pt-br
unauthorized_ispb	You submitted an account registered with unauthorized ISPB	Você enviou uma conta cadastrada com ISPB não autorizado

Callbacks

Request samples

Payload

Content type

application/json

Example

{"callbackUrl": "https://client.callback.com/notify-payin",
"customNumber": "YOUR-CODE1234",
"title": {"expireDate": "2024-12-31T23:59:59",
"amountInCents": 8652,
"instructions": "Esse Pix é referente ao pedido 123 na loja abcd"
},
"buyer": {"name": "Maria da Silva",
"email": "buyer-email@wepayments.com.br",
"document": {"number": "34960826312",
"type": "CPF"
}
}
}

Response samples

201
400
403
422

Content type

application/json

Example

{"id": "28018",
"key": "e1ebf9d914174902a76a5af436f091d09cca0b1e9ad8984b5dcdfeead67ce6b8",
"clientId": 1,
"clientName": "Your company",
"senderName": null,
"senderHelpdesk": null,
"buyerName": "Maria da Silva",
"buyerDocument": "34960826312",
"buyerEmail": "buyer-email@wepayments.com.br",
"customNumber": "YOUR-CODE1234",
"ourNumber": 17530,
"digitableLine": "pix.example.com/qr/2353c790eefb11eaadc10242ac120002",
"barCodeNumber": null,
"status": {"id": 1,
"name": "Created"
},
"sender": {"name": null,
"document": null,
"helpdesk": null
},
"typePayin": "pix",
"instructions": "Esse Pix é referente ao pedido 123 na loja abcd",
"amountCents": 8652,
"paidAmountCents": null,
"paidAt": null,
"expiresAt": "2024-12-31 23:59:59",
"createdAt": "2024-02-21T19:15:00.000000Z",
"fine": null,
"discount": null,
"splits": [ ],
"statusHistory": {"status": {"id": 1,
"name": "Created"
},
"id": 48859,
"updatedAt": "2024-02-21T19:15:04.000000Z"
},
"refundMode": "FULL_REFUND_CLIENT",
"refundAmountCents": 0,
"payinRefunds": [ ],
"payin_substatus": null,
"kyc": null
}

Callback payload samples

Callback

POST: https://your.endpoint.to.update

Content type

application/json

Example

{"id": "28018",
"key": "e1ebf9d914174902a76a5af436f091d09cca0b1e9ad8984b5dcdfeead67ce6b8",
"clientId": 1,
"clientName": "Your company",
"senderName": null,
"senderHelpdesk": null,
"buyerName": "Maria da Silva",
"buyerDocument": "34960826312",
"buyerEmail": "buyer-email@wepayments.com.br",
"customNumber": "YOUR-CODE1234",
"ourNumber": 17530,
"digitableLine": "pix.example.com/qr/2353c790eefb11eaadc10242ac120002",
"barCodeNumber": null,
"status": {"id": 1,
"name": "Created"
},
"sender": {"name": null,
"document": null,
"helpdesk": null
},
"typePayin": "pix",
"instructions": "Esse Pix é referente ao pedido 123 na loja abcd",
"amountCents": 8652,
"paidAmountCents": null,
"paidAt": null,
"expiresAt": "2024-12-31 23:59:59",
"createdAt": "2024-02-21T19:15:00.000000Z",
"fine": null,
"discount": null,
"splits": [ ],
"statusHistory": {"status": {"id": 1,
"name": "Created"
},
"id": 48859,
"updatedAt": "2024-02-21T19:15:04.000000Z"
},
"refundMode": "FULL_REFUND_CLIENT",
"refundAmountCents": 0,
"payinRefunds": [ ],
"payin_substatus": null,
"kyc": null
}

Create a new billet payment charge.

Create a new payment slip

fine.interest configuration

When creating a bank slip charge, the max interest amount allowed is 20%. Either Pixor Credit Card charges, the interest configuration remains the same.

Expiration date format

The expireDate field in Boleto is formatted as "YYYY-MM-DD". Ex.: 2021-12-31

Possible charge statuses

PAYIN_CREATED : 1; The first status when the payin is created.
PAYIN_CANCELED : 2; Payin canceled due to expiration.
PAYIN_PAID : 3; Payin was paid.
PAYIN_CREDITED : 4; Payin was paid and the amount was credited on your wallet.
PAYIN_DROP_REQUESTED : 5; Payin expiration requested.

Possible refund mode

When creating a charge, you must know how the wallet values will be debited if a refund is requested.
You can choose from the 3 options below

FULL_REFUND_CLIENT: If none is informed, it will be selected by default. In this mode, the refund amount will be fully debited from the client wallet.
FULL_REFUND_RECIPIENT: In this mode, the refund amount will be fully debited from the sub-portfolio or sub-client informed in the split. In this mode, the refund will only be allowed if you have a maximum of 1 split.
REFUND_BY_SPLIT: In this mode, the refund amount will be debited proportionally as informed in the split and main wallet. In this mode, the refund will only be allowed if you have a maximum of 1 split.

Payment page

We provide you a simple payment page that renders the credit-card, boleto or Pix QR code so the user can access it and view the instructions to pay the charge. For security reasons, it is not possible to open the payment page within an iframe.

To use the page you will need the key field that is returned in this method.

The payment page url is: https://pagar.goboleto.com/?hash={key}.

In sandbox environment the page url is: https://pagar.sandbox.goboleto.com/?hash={key}

Authorizations:

bearerAuth

Request Body schema: application/json

clientId	integer or null <int32> Use of clientID to create payments. Is mandatory if there is more than one account under my umbrella.
callbackUrl	string or null <uri> The url where we will submit the callbacks.
customNumber	string Your identification number, it must be unique on our database.
required	object Payment instructions.
required	object Use this object to inform the legal name of the final beneficiary, it could be your company’s name or the company you are providing a service for. Final Beneficiary is a person or a company that will receive the amount paid .
required	object The person that you are charging.
	object Discount when a certain date is reached.
	object Fine when the expiration date is reached.
	Array of objects[ items ] Splits are avaiable if you want to credit more than one wallet with the charged paid amount.
refundMode	string Default: "FULL_REFUND_CLIENT" Enum: "FULL_REFUND_CLIENT" "FULL_REFUND_RECIPIENT" "REFUND_BY_SPLIT" Enum of some refund options

Responses

Callbacks

Request samples

Payload

Content type

application/json

Example

{"callbackUrl": "https://client.callback.com/notify-payin",
"customNumber": "1234",
"title": {"expireDate": "2020-04-20",
"amountInCents": 8652,
"instructions": "Esse payin é referente à compra do produto X"
},
"buyer": {"name": "Josefino da Silva",
"document": {"number": "01234567890",
"type": "CPF"
},
"address": {"street": "Rua da praça",
"number": "123",
"complement": "conjunto comercial",
"zipCode": "99090900",
"city": "Curitiba",
"district": "Centro",
"stateCode": "PR"
}
},
"sender": {"name": "Sender name",
"document": "Sender document",
"helpdesk": "Sender helpdesk"
}
}

Response samples

201

Content type

application/json

{"key": "5ec31949bfe92627afc96a8ed20126a1103ddb5534fasc20a9bb51df0934e412",
"clientId": 0,
"clientName": "Name",
"buyerName": "Buyer",
"buyerDocument": "00000000000",
"customNumber": "0000000000",
"ourNumber": "922222222222",
"digitableLine": "00000.00000 00000.00000 00000.000000 0 00000000000000",
"barCodeNumber": "00000000000000000000000000000000000000000000",
"status": [{"id": 1
},
{"name": "Criado"
}
],
"typePayin": "boleto",
"amountCents": 5000,
"paidAmountCents": null,
"paidAt": null,
"expiresAt": "2021-12-31 00:00:00",
"createdAt": "2021-01-31T13:33:07.000000Z",
"fine": null,
"discount": null,
"splits": [{"walletOwner": "client 1",
"walletUUID": "wallet1",
"percent": 40,
"amountInCents": null
},
{"walletOwner": "client 2",
"walletUUID": "wallet 2",
"percent": 60,
"amountInCents": null
}
],
"statusHistory": [{"status": {"id": 1,
"name": "Created"
},
"updatedAt": "2021-01-01T13:33:10.000000Z"
}
],
"agreement": {"number": "666666",
"digit": "6",
"agency": "9999",
"assignorCode": "9999/666666-6"
}
}

Callback payload samples

Callback

POST: https://your.endpoint.to.update

Content type

application/json

Example

{"id": "28018",
"key": "e1ebf9d914174902a76a5af436f091d09cca0b1e9ad8984b5dcdfeead67ce6b8",
"clientId": 1,
"clientName": "Your company",
"senderName": null,
"senderHelpdesk": null,
"buyerName": "Maria da Silva",
"buyerDocument": "34960826312",
"buyerEmail": "buyer-email@wepayments.com.br",
"customNumber": "YOUR-CODE1234",
"ourNumber": 17530,
"digitableLine": "pix.example.com/qr/2353c790eefb11eaadc10242ac120002",
"barCodeNumber": null,
"status": {"id": 1,
"name": "Created"
},
"sender": {"name": null,
"document": null,
"helpdesk": null
},
"typePayin": "pix",
"instructions": "Esse Pix é referente ao pedido 123 na loja abcd",
"amountCents": 8652,
"paidAmountCents": null,
"paidAt": null,
"expiresAt": "2024-12-31 23:59:59",
"createdAt": "2024-02-21T19:15:00.000000Z",
"fine": null,
"discount": null,
"splits": [ ],
"statusHistory": {"status": {"id": 1,
"name": "Created"
},
"id": 48859,
"updatedAt": "2024-02-21T19:15:04.000000Z"
},
"refundMode": "FULL_REFUND_CLIENT",
"refundAmountCents": 0,
"payinRefunds": [ ],
"payin_substatus": null,
"kyc": null
}

Create a new credit card charge

About credit-card charges

Credit card charges are created as PAYIN_CREATED status. It goes from PAYIN_CREATED to PAYIN_AWAITING_APPROVAL when the checkout is requested.

The checkout can be done in 2 different ways:

Payments page
Transparent checkout

Payment page

We provide you a simple payment page where you can view the instructions and request the payment. To use the page you will need the key field, which is returned when you create the charge. For security reasons, it is not possible to open the payment page within an iframe.

The payment page url is: https://pagar.goboleto.com/?hash={key}. In sandbox environment the page url is: https://pagar.sandbox.goboleto.com/?hash={key}

After creating the charge, access to the credit-card checkout will be available via the URL of our payments page (in the description above).

The following additional information will be required to proceed with the checkout:

Credit card number
Cardholder Name
Address (that will be the payer' credit-card billing address)
Number of installments

Transparent checkout

The transparent checkout is a one-step process to create and pay the charge.
There is some additional data to request a transparent checkout.

When creating a credit-card charge, if the input checkout is present within the payload the charge will be created and processed.

To get all required data to process a transparent checkout our SDK must be implemented.

For further information, please read our documentation in the link below about Transparent Checkout and how to integrate our SDK: https://docs.wepayout.co/pt/docs/payin/transparent_checkout/

Transparent checkout with stored credit-card

To perform the fast-checkout action, you only need to inform the card_id parameter inside the checkout object. This parameter refers to the saved credit card ID. To recover this parameter, just consult the list of cards saved for a customer.

2 endpoints are available for listing customer information and their saved cards:

List of customers for a given client: https://docs.wepayout.co/api/payin/#tag/Charge/operation/get-v1-clients-clientId-customers
List of cards for a given customer: /v1/payin/customers/{customerId}/cards

If you inform the card_id parameter you MUST NOT inform token and payment_method_id parameters.

Optional inputs (Payment page)

During the checkout process, we provide the option to redirect the user to a custom success or failure page (according to the transaction status). Here follows the options for redirection:

external_url.redirect_on_success: The URL where the user will be redirected after a successful credit-card checkout.
external_url.redirect_on_fail: The URL where the user will be redirected after a failed credit-card checkout

You can also provide a custom image URL to be displayed at our payment page by sending the external_url.checkout_image_url input.

All 3 options are optional, and the user will be redirected to our default pages after the checkout if any of the redirect urls are present as well as the checkout image.

Expiration date format

The expireDate field is formatted as "YYYY-MM-DDTH:I:S". Ex.: 2021-12-31T23:59:59

Possible charge statuses

PAYIN_CREATED : 1; The first status when the payin is created.
PAYIN_CANCELED : 2; Payin canceled due to expiration.
PAYIN_PAID : 3; Payin was paid.
PAYIN_CREDITED : 4; Payin was paid and the amount was credited on your wallet.
PAYIN_DROP_REQUESTED : 5; Payin expiration requested.
PAYIN_AWAITING_APPROVAL : 6; When the checkout is made, the charge goes from PAYIN_CREATED to PAYIN_AWAITING_APPROVAL (intermediate status) before the confirmation or any other payment final status occurs.
PAYIN_REJECTED : 7; The payment was rejected and could not be processed.

Possible refund mode

When creating a charge, you must know how the wallet values will be debited if a refund is requested.
You can choose from the 3 options below

FULL_REFUND_CLIENT: If none is informed, it will be selected by default. In this mode, the refund amount will be fully debited from the client wallet.
FULL_REFUND_RECIPIENT: In this mode, the refund amount will be fully debited from the sub-portfolio or sub-client informed in the split. In this mode, the refund will only be allowed if you have a maximum of 1 split.
REFUND_BY_SPLIT: In this mode, the refund amount will be debited proportionally as informed in the split and main wallet. In this mode, the refund will only be allowed if you have a maximum of 1 split.

Regarding the safety of our customers, it is very important to emphasize that we DO NOT keep any information about the credit-card and all credit-card information filled in the checkout page are only used once to confirm the transaction.

For any further questions you can contact us through our customer service channels.

Authorizations:

bearerAuth

Request Body schema: application/json

callbackUrl	string <uri> The url where we will submit the callbacks.
customNumber	string <= 255 characters Your identification number, it must be unique on our database.
clientId	integer or null <int32> The use of clientID to create payments. Is mandatory if there is more than one account under the same clientId.
required	object Payment instructions.
required	object The person that you are charging object.
refundMode	string Default: "FULL_REFUND_CLIENT" Enum: "FULL_REFUND_CLIENT" "FULL_REFUND_RECIPIENT" "REFUND_BY_SPLIT" Enum of some refund options.
	Array of objects[ items ] Splits are avaiable if you want to credit more than one wallet with the charged paid amount.
required	object REQUIRED FOR CREDIT-CARD CHARGES. Use this object to inform the legal name of the final beneficiary, it could be your company’s name or the company you are proving a service for. Final Beneficiary is a person or a company that will receive the amount paid trough the boleto.
	object Payer infromations.
statement_descriptor required	string^\S{1,13}\z Short description shown at the credit-card bill.
required	Array of objects non-empty [ items ] Array with product metadata.
use_3ds	integer or null Default: null Enum: 0 1 null Flag to inform that the charge must validate through three d secure mode

Responses

Callbacks

Request samples

Payload

Content type

application/json

Example

{"callbackUrl": "https://client.callback.com/notify-payin",
"customNumber": "1234",
"title": {"expireDate": "2020-04-20",
"amountInCents": 8652,
"instructions": "Esse payin é referente à compra do produto X"
},
"buyer": {"name": "Josefino da Silva",
"document": {"number": "01234567890",
"type": "CPF"
},
"address": {"street": "Rua da praça",
"number": "123",
"complement": "conjunto comercial",
"zipCode": "99090900",
"city": "Curitiba",
"district": "Centro",
"stateCode": "PR"
}
},
"sender": {"name": "Sender name",
"document": "Sender document",
"helpdesk": "Sender helpdesk"
}
}

Response samples

201
403
404

Content type

application/json

{"id": "28018",
"key": "e1ebf9d914174902a76a5af436f091d09cca0b1e9ad8984b5dcdfeead67ce6b8",
"clientId": 1,
"clientName": "Your company",
"senderName": null,
"senderHelpdesk": null,
"buyerName": "Maria da Silva",
"buyerDocument": "34960826312",
"buyerEmail": "buyer-email@wepayments.com.br",
"customNumber": "YOUR-CODE1234",
"ourNumber": null,
"digitableLine": null,
"barCodeNumber": null,
"status": {"id": 1,
"name": "awaiting approval"
},
"sender": {"name": null,
"document": null,
"helpdesk": null
},
"typePayin": "credit-card",
"instructions": "Esse Pagamento é referente ao pedido 123 na loja abcd",
"amountCents": 8652,
"paidAmountCents": null,
"paidAt": null,
"expiresAt": "2024-12-31 23:59:59",
"createdAt": "2024-02-21T19:15:00.000000Z",
"fine": null,
"discount": null,
"splits": [ ],
"statusHistory": [{"status": {"id": 1,
"name": "Created"
}
},
{"status": {"id": 6,
"name": "awaiting approval"
},
"id": 48859,
"updatedAt": "2024-02-21T19:15:04.000000Z"
}
],
"refundMode": "FULL_REFUND_CLIENT",
"refundAmountCents": 0,
"payinRefunds": [ ],
"payin_substatus": null,
"kyc": null,
"installments": [ ],
"hasAdvancement": true,
"use3ds": false
}

Callback payload samples

Callback

POST: https://your.endpoint.to.update

Content type

application/json

Example

{"id": "28018",
"key": "e1ebf9d914174902a76a5af436f091d09cca0b1e9ad8984b5dcdfeead67ce6b8",
"clientId": 1,
"clientName": "Your company",
"senderName": null,
"senderHelpdesk": null,
"buyerName": "Maria da Silva",
"buyerDocument": "34960826312",
"buyerEmail": "buyer-email@wepayments.com.br",
"customNumber": "YOUR-CODE1234",
"ourNumber": 17530,
"digitableLine": "pix.example.com/qr/2353c790eefb11eaadc10242ac120002",
"barCodeNumber": null,
"status": {"id": 1,
"name": "Created"
},
"sender": {"name": null,
"document": null,
"helpdesk": null
},
"typePayin": "pix",
"instructions": "Esse Pix é referente ao pedido 123 na loja abcd",
"amountCents": 8652,
"paidAmountCents": null,
"paidAt": null,
"expiresAt": "2024-12-31 23:59:59",
"createdAt": "2024-02-21T19:15:00.000000Z",
"fine": null,
"discount": null,
"splits": [ ],
"statusHistory": {"status": {"id": 1,
"name": "Created"
},
"id": 48859,
"updatedAt": "2024-02-21T19:15:04.000000Z"
},
"refundMode": "FULL_REFUND_CLIENT",
"refundAmountCents": 0,
"payinRefunds": [ ],
"payin_substatus": null,
"kyc": null
}

Returns a payin by KEY.

You can check the payin using one of it's identifications parameters. Every transaction will generate a unique id code, key code, with this codes you will find the charge.

Authorizations:

bearerAuth

path Parameters

key required	integer Value corresponding to the key being entered.
keyType required	string Enum: "id" "key" "ourNumber" Example: key Type of key that will be used when querying a charge.

Responses

Response samples

200
403
404

Content type

application/json

{"id": 23644,
"key": "e1ebf9d914174902a76a5af436f091d09cca0b1e9ad8984b5dcdfeead67ce6b8",
"clientName": "Your company",
"buyerName": "Maria da Silva",
"buyerDocument": 34960826312,
"buyerEmail": "buyer-email@wepayments.com.br",
"customNumber": "YOUR-CODE1234",
"ourNumber": 17530,
"digitableLine": "21890.01007 03115.798807 57888.867884 4 96430000005074",
"barCodeNumber": "21894964300000050740010003115798805788886788",
"status": {"name": 3,
"id": "paid"
},
"typePayin": "boleto",
"amountCents": 8652,
"paidAmountCents": 8652,
"paidAt": "2024-02-25T14:15:22Z",
"expiresAt": "2024-03-24T14:15:22Z",
"createdAt": "2024-02-24T14:15:22Z",
"fine": null,
"discount": null,
"statusHistory": [{"status": {"id": 3,
"name": "paid"
},
"updatedAt": "2024-02-25T14:15:22Z"
},
{"status": {"id": 1,
"name": "created"
},
"updatedAt": "2024-02-24T14:15:22Z"
}
],
"sender": {"name": "Final beneficiary name",
"document": 66917404000152,
"helpdesk": "final-beneficiary.com.br"
},
"payinRefunds": [{"id": 1,
"payinId": 1,
"statusId": 2,
"user": {"id": 1,
"name": "Usuário de Teste"
},
"clientId": 1,
"amountCents": 100,
"statuses": [{"id": 1,
"statusId": 1,
"name": "Solicitado",
"notification": 1,
"createdAt": "2022-03-11T17:14:47.000000Z"
},
{"id": 2,
"statusId": 2,
"name": "Pago",
"notification": 1,
"createdAt": "2022-03-11T17:14:49.000000Z"
}
],
"endToEndId": "EFASA321654987456ASAS123",
"reason": "Devolvendo valores de teste",
"callbackUrl": "https://payin-refund.requestcatcher.com/",
"createdAt": "2022-03-11T17:31:03.000000Z",
"updatedAt": "2022-03-11T17:31:05.000000Z"
}
],
"refundAmountCents": 1000,
"reason_canceled": {"id": 0,
"name": "string"
},
"agreement": {"number": "666666",
"digit": "6",
"agency": "9999",
"assignorCode": "9999/666666-6"
}
}

Returns a the printable payin HTML from a provided KEY.

Available only for boleto charges.

Authorizations:

bearerAuth

path Parameters

key

required

integer

The Key of the payin.

Responses

Response samples

200

Content type

application/json

"\"<style></style><div>here will be the charge html</div>\""

Credit card status

Retrieves information about a credit-card charge current status

Authorizations:

bearerAuth

path Parameters

key

required

integer

The Key of the payin.

Responses

Response samples

200
404

Content type

application/json

{"status": true,
"data": {"key": "string",
"status_id": 0,
"status_detail": 0,
"status_detail_description": "string",
"external_urls": {"redirect_on_success": "string",
"redirect_on_fail": "string"
},
"can_checkout": true,
"three_ds_data": {"external_resource_url": "string",
"creq": "string"
}
},
"message": "string"
}

Request Payin Cancelation

Request cancelation for Payins of a type boleto or pix

Payins must be created for at least the following time to be reason_canceled:

pix 5 minutes
boleto 30 minutes

Only Payins in status = created can be canceled. Payins in any other status will no be canceled

pix Payins will be canceled instantly
boleto Payins requires at least 1 day to change its status from drop requested to canceled since its cancelling process must wait a response from the processor

Authorizations:

bearerAuth

path Parameters

id

required

string

Identification of the Payin which is being canceled

Responses

Response samples

200
422

Content type

application/json

{"status": true,
"data": { },
"message": "string"
}

Customers list

Retrieves a list of customers with credit-cards serialized for fast checkouts

Authorizations:

bearerAuth

path Parameters

clientId

required

string

Your client ID

Responses

Response samples

200

Content type

application/json

[{"id": 0,
"name": "string",
"email": "user@example.com"
}
]

Customer credit-card list

List of credit-cards from a given customer

Authorizations:

bearerAuth

path Parameters

customerId

required

string

Customer ID

Responses

Response samples

200

Content type

application/json

[{"id": 123,
"holder": "John Doe",
"card_last_four": "5214",
"payment_method_id": "visa",
"expiry_date": "01/2023"
}
]

Recipient

Creates a recipient to be used on splits.

Authorizations:

bearerAuth

path Parameters

clientId

required

integer

The Client ID.

Request Body schema: application/json

name required	string recipient's name.
bank_code required	string bank code is mandatory if Pixkey is empety.
bank_branch required	string bank branch is mandatory if Pixkey is empety.
bank_branch_digit required	string bank branch digit is mandatory if Pixkey is empety.
account required	string account is mandatory if Pixkey is empety.
account_digit required	string account digit is mandatory if Pixkey is empety.
account_type required	string Value: "\"c\" for checking and \"s\" for savings" account type is mandatory if Pixkey is empety.
pix_key required	string Pixkey is mandatory if the bank data is empty
email required	string recipient's e-mail.
document required	string recipient's document number.
document_type required	string Value: "\"cpf\" or \"cnpj\"" recipient's document type.

Responses

Request samples

Payload

Content type

application/json

{"name": "My Recipient",
"bank_code": "001",
"bank_branch": "6955",
"bank_branch_digit": "0",
"account": "1146208",
"account_digit": "6",
"account_type": "c",
"pix_key": "01234567890",
"email": "recipient1@gmail.com",
"document": "01234567890",
"document_type": "cpf"
}

Response samples

200

Content type

application/json

{"status": true,
"data": {"id": 5,
"wallet_uuid": "3e40f8f1-9f70-4f5d-97f9-90483027dfaa",
"name": "My Recipient",
"bank_code": "001",
"bank_name": "001 - BANCO DO BRASIL S/A",
"bank_branch": "6955",
"bank_branch_digit": "0",
"account": "1146208",
"account_digit": "6",
"account_type": "c",
"pix_key": "01234567890",
"document": "01234567890",
"document_type": "cpf",
"email": "recipient1@gmail.com",
"created_at": "2020-07-20T13:19:10.000000Z",
"updated_at": "2020-07-20T13:19:10.000000Z"
},
"message": "Recipient created"
}

Updates a recipient.

Authorizations:

bearerAuth

path Parameters

clientId required	integer The Client ID.
recipientId required	integer The Recipient ID.

Request Body schema: application/json

name required	string recipient's name.
bank_code required	string bank code is mandatory if Pixkey is empety.
bank_branch required	string bank branch is mandatory if Pixkey is empety.
bank_branch_digit required	string bank branch digit is mandatory if Pixkey is empety.
account required	string account is mandatory if Pixkey is empety.
account_digit required	string account digit is mandatory if Pixkey is empety.
account_type required	string Value: "\"c\" for checking and \"s\" for savings" account type is mandatory if Pixkey is empety.
pix_key required	string Pixkey is mandatory if the bank data is empty
email required	string recipient's e-mail.
document required	string recipient's document number.
document_type required	string Value: "\"cpf\" or \"cnpj\"" recipient's document type.

Responses

Request samples

Payload

Content type

application/json

{"name": "My Recipient",
"bank_code": "001",
"bank_branch": "6955",
"bank_branch_digit": "0",
"account": "1146208",
"account_digit": "6",
"account_type": "c",
"pix_key": "01234567890",
"email": "recipient1@gmail.com",
"document": "01234567890",
"document_type": "cpf"
}

Response samples

200

Content type

application/json

{"status": true,
"data": {"id": 5,
"wallet_uuid": "3e40f8f1-9f70-4f5d-97f9-90483027dfaa",
"name": "My Recipient",
"bank_code": "001",
"bank_name": "001 - BANCO DO BRASIL S/A",
"bank_branch": "6955",
"bank_branch_digit": "0",
"account": "1146208",
"account_digit": "6",
"account_type": "c",
"pix_key": "01234567890",
"document": "01234567890",
"document_type": "cpf",
"email": "recipient1@gmail.com",
"created_at": "2020-07-20T13:19:10.000000Z",
"updated_at": "2020-07-20T13:19:10.000000Z"
},
"message": "Recipient created"
}

Get recipient by ID.

Return a recipient information using it's ID

Authorizations:

bearerAuth

path Parameters

clientId required	integer The Client ID.
recipientId required	integer The Recipient ID.

Responses

Response samples

200

Content type

application/json

{"id": 5,
"wallet_uuid": "3e40f8f1-9f70-4f5d-97f9-90483027dfaa",
"name": "My Recipient",
"bank_code": "001",
"bank_name": "001 - BANCO DO BRASIL S/A",
"bank_branch": "6955",
"bank_branch_digit": "0",
"account": "1146208",
"account_digit": "6",
"account_type": "c",
"pix_key": "01234567890",
"document": "01234567890",
"document_type": "cpf",
"email": "recipient1@gmail.com",
"created_at": "2020-07-20T13:19:10.000000Z",
"updated_at": "2020-07-20T13:19:10.000000Z"
}

Create withdrawal for recipient

Authorizations:

bearerAuth

path Parameters

clientId

required

string

Your client id

header Parameters

Accept	string application/json
Content-Type	string application/json

Request Body schema: application/json

amount_cents required	integer <int64> [ 1 .. 99999999 ] Withdrawal amount in cents.
recipient_id	integer or null Your recipient id

Responses

Request samples

Payload

Content type

application/json

{"amount_cents": 10000,
"recipient_id": 0
}

Response samples

201

Content type

application/json

{"id": 0,
"client": {"id": 0,
"name": "string",
"type": "string"
},
"status": {"id": 0,
"name": "string"
},
"amount_cents": 0,
"bank_branch": "string",
"bank_branch_digit": "string",
"pix_key": "string",
"account": "string",
"account_digit": "string",
"payout_sent": 0,
"notes": "string",
"custom_code": "string",
"converted_amount_cents": 0,
"exchange_rate": 0,
"exchange_bank": "string",
"file_location": "string",
"created_at": "string",
"updated_at": "string",
"bank": {"id": 0,
"name": "string",
"code": "string"
}
}

Client Balance

Get client balance by ID.

Returns a client or recipient balance

Authorizations:

bearerAuth

path Parameters

clientId

required

integer

The Client ID.

query Parameters

recipientId

string

Use this if you want to retrieve a specific recipient balance

Responses

Response samples

200

Content type

application/json

{"status": true,
"data": {"balance": 10000,
"available_balance_cents": 9319,
"updated_at": "2020-07-20T10:55:38-03:00"
},
"message": "Client balance amount in cents"
}

Payin Refund

Create Refund

Create a new refund.
To initiate the refund, the unique identifier of the Pix payment or credit card must be informed in the "payinId" parameter.

Possible refunds statuses

status_code	status	explanation
`2`	REQUESTED	Refund requested.
`4`	PAID	Refund was paid.
`5`	ERROR	Refund Error.

Some important rules

Only charges credited to the wallet can be refunded.
The customer must have at least the refund amount available in the wallet
Pix , can only be returned with 90 days or less. Credit card , 180 days or less.

Authorizations:

bearerAuth

path Parameters

payinId

required

string

Identification of the charge to be refunded

Request Body schema: application/json

amountCents required	integer [ 0 .. 10000000 ] Amount to be refunded
reason	string [ 1 .. 191 ] characters Reason for refund
callbackUrl	string [ 1 .. 191 ] characters URL for sending the webhook
	Array of objects[ items ] Only if in the creation of the charge was informed in the field "refundMode" the value: "REFUND_BY_SPLIT"

Responses

Request samples

Payload

Content type

application/json

{"amountCents": 10000,
"reason": "refund reason",
"callbackUrl": "https://wpo.requestcatcher.com/"
}

Response samples

201
403
404

Content type

application/json

{"id": 1,
"payinId": 1,
"statusId": 2,
"user": {"id": 1,
"name": "Usuário de Teste"
},
"clientId": 1,
"amountCents": 100,
"statuses": [{"id": 1,
"statusId": 1,
"name": "Solicitado",
"notification": 1,
"createdAt": "2022-03-11T17:14:47.000000Z"
},
{"id": 2,
"statusId": 2,
"name": "Pago",
"notification": 1,
"createdAt": "2022-03-11T17:14:49.000000Z"
}
],
"endToEndId": "EFASA321654987456ASAS123",
"reason": "Devolvendo valores de teste",
"callbackUrl": "https://payin-refund.requestcatcher.com/",
"createdAt": "2022-03-11T17:31:03.000000Z",
"updatedAt": "2022-03-11T17:31:05.000000Z"
}

Get Refund by id

Returns the refund using its unique identifier

Authorizations:

bearerAuth

path Parameters

payinRefundId

required

string

Responses

Response samples

200
403
404

Content type

application/json

{"id": 1,
"payinId": 1,
"statusId": 2,
"user": {"id": 1,
"name": "Usuário de Teste"
},
"clientId": 1,
"amountCents": 100,
"statuses": [{"id": 1,
"statusId": 1,
"name": "Solicitado",
"notification": 1,
"createdAt": "2022-03-11T17:14:47.000000Z"
},
{"id": 2,
"statusId": 2,
"name": "Pago",
"notification": 1,
"createdAt": "2022-03-11T17:14:49.000000Z"
}
],
"endToEndId": "EFASA321654987456ASAS123",
"reason": "Devolvendo valores",
"callbackUrl": "https://payin-refund.requestcatcher.com/",
"createdAt": "2022-03-11T17:31:03.000000Z",
"updatedAt": "2022-03-11T17:31:05.000000Z"
}

Subscription

List Subscription

List the subscriptions

Authorizations:

bearerAuth

query Parameters

id	number Subscription code
buyer_document	string Buyer Document
invoice	string Invoice
status_id	string Enum: "21" "22" "23" Subscription Status Id
client_id	string Client Code
created_before	string Created before
created_after	string Created after
per_page	string Per page
page	string Page
sort	string Enum: "ASC" "DESC" sort
order_by	string Order By

Responses

Response samples

200

Content type

application/json

[{"id": 0,
"invoice": "string",
"callbackUrl": "string",
"client": {"id": 0,
"name": "string"
},
"status": {"id": 21,
"name": "ACTIVE"
},
"instructions": "string",
"amountCents": 0,
"sender": {"name": "string",
"document": "string",
"helpdesk": "string"
},
"buyer": {"name": "string",
"email": "string",
"document": {"number": "string",
"type": "CPF"
}
},
"dateNextIssue": "2019-08-24",
"dateLastPaid": "2019-08-24",
"dateFirst": "2019-08-24",
"daysBeforeExpiration": 0,
"frequency": "MONTHLY",
"quantity": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]

Create Subscription

Create a new subscription

Attention points

When selecting WEEKLY for subscription frequency, the maximum value allowed for the dateFirt field is 7
When selecting MONTHLY for subscription frequency, the maximum value allowed for the dateFirt field is 30
The charges generated from the subscription are of the Pix type
Subscription only sends webhook to expired status.
The same value entered for callbackUrl will be used to notify billing and subscription statuses.

Authorizations:

bearerAuth

Request Body schema: application/json

invoice required	string [ 1 .. 191 ] characters
callbackUrl	string [ 1 .. 191 ] characters The callback for we send status updates.
instructions required	string non-empty Subscription instructions.
amountCents required	integer The subscription amount is in cents.
	object Sender details.
required	object Buyer details.
dateFirst required	string <date> non-empty The first subscription payment.
daysBeforeExpiration required	integer The number of days before expiration to send an email to remind the buyer about the subscription charge.
frequency required	string non-empty Enum: "WEEKLY" "MONTHLY" The subscription frequency.
quantity	integer >= 2 The number of months or weeks for the subscription depends on the option you choose in the `frequency` field.
clientId required	integer The client whom you are charging.

Responses

Request samples

Payload

Content type

application/json

{"invoice": "string",
"callbackUrl": "string",
"instructions": "string",
"amountCents": 0,
"sender": {"name": "string",
"document": "string",
"helpdesk": "string"
},
"buyer": {"name": "string",
"email": "string",
"document": {"number": "string",
"type": "string"
}
},
"dateFirst": "string",
"daysBeforeExpiration": 0,
"frequency": "string",
"quantity": "string",
"clientId": 0
}

Response samples

201
422

Content type

application/json

{"id": 0,
"invoice": "string",
"callbackUrl": "string",
"client": {"id": 0,
"name": "string"
},
"status": {"id": 21,
"name": "ACTIVE"
},
"instructions": "string",
"amountCents": 0,
"sender": {"name": "string",
"document": "string",
"helpdesk": "string"
},
"buyer": {"name": "string",
"email": "string",
"document": {"number": "string",
"type": "CPF"
}
},
"dateNextIssue": "2019-08-24",
"dateLastPaid": "2019-08-24",
"dateFirst": "2019-08-24",
"daysBeforeExpiration": 0,
"frequency": "MONTHLY",
"quantity": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Get Subscription By ID

Authorizations:

bearerAuth

path Parameters

id

required

string

Subscription Code

Responses

Response samples

200

Content type

application/json

{"id": 0,
"invoice": "string",
"callbackUrl": "string",
"client": {"id": 0,
"name": "string"
},
"status": {"id": 21,
"name": "ACTIVE"
},
"instructions": "string",
"amountCents": 0,
"sender": {"name": "string",
"document": "string",
"helpdesk": "string"
},
"buyer": {"name": "string",
"document": {"number": "string",
"type": "CPF"
}
},
"dateNextIssue": "2019-08-24",
"dateLastPaid": "2019-08-24",
"dateFirst": "2019-08-24",
"daysBeforeExpiration": 0,
"frequency": "MONTHLY",
"quantity": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Cancel Subscription By ID

Authorizations:

bearerAuth

path Parameters

id

required

string

Subscription Code

Responses

Response samples

200
400

Content type

application/json

{"id": 0,
"invoice": "string",
"callbackUrl": "string",
"client": {"id": 0,
"name": "string"
},
"status": {"id": 1,
"name": "ACTIVE"
},
"instructions": "string",
"amountCents": 0,
"sender": {"name": "string",
"document": "string",
"helpdesk": "string"
},
"buyer": {"name": "string",
"document": {"number": "string",
"type": "CPF"
}
},
"dateNextIssue": "2019-08-24",
"dateLastPaid": "2019-08-24",
"dateFirst": "2019-08-24",
"daysBeforeExpiration": 0,
"frequency": "MONTHLY",
"quantity": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Get Preview

Preview

Creates preview of the due date and generation date of future charges.
A total of maximum 6 charges will be returned.

Authorizations:

bearerAuth

Request Body schema: application/json

dateFirst required	string <date> non-empty First subscription payment.
daysBeforeExpiration required	integer If `frequency` is equal to `MONTHLY`, the minimum number is 1 and the maximum is 30; otherwise, if `frequency` is equal to `WEEKLY`, the minimum is 1 and the maximum is 7.
frequency required	string non-empty Enum: "WEEKLY" "MONTHLY" Frequency of the subscription payment.
quantity	integer >= 2 Number of payments in the list.

Responses

Request samples

Payload

Content type

application/json

{"dateFirst": "string",
"daysBeforeExpiration": 0,
"frequency": "string",
"quantity": "string"
}

Response samples

200
422

Content type

application/json

[{"index": 0,
"dateExpiration": "string",
"dateIssue": "string"
}
]

Client | Sub-merchant

Create Sub-Merchant

Authorizations:

bearerAuth

Request Body schema: application/json

parent_id required	integer Your client id, informed by WE
company_name required	string <= 255 characters Name for your sub merchant registration
type required	string Enum: "national" "crossborder"
name required	string <= 255 characters Second name for your sub merchant registration, this will appear in the reports.
legal_name required	string Legal name of your sub-merchant
legal_entity_number	string Your sub merchant's legal document
owner_name required	string <= 45 characters Name of the legal representative of the sub merchant
fee_paid_cents required	integer [ 0 .. 999999999 ] Default: null Fee in cents per paid billet. Enter null if you don't use the product, otherwise it must be greater than or equal to the parent customer.client.
fee_dropped_cents required	integer [ 0 .. 999999999 ] Default: null Fee in cents per dropped billet. Enter null if you don't use the product, otherwise it must be greater than or equal to the parent customer.
fee_paid_pix_cents required	integer [ 0 .. 999999999 ] Default: null Fee in cents per paid pix. Enter null if you don't use the product, otherwise it must be greater than or equal to the parent customer.
fee_dropped_pix_cents required	integer [ 0 .. 999999999 ] Default: null Fee in cents per dropped pix. Enter null if you don't use the product, otherwise it must be greater than or equal to the parent customer.
fee_withdrawal_cents required	integer [ 0 .. 999999999 ] Fee in cents per paid withdrawal. Enter null if you don't use the product, otherwise it must be greater than or equal to the parent customer.
fee_recipient_withdrawal_cents required	integer [ 0 .. 999999999 ] Fee in cents per withdrawal paid from recipient. Enter null if you don't use the product, otherwise it must be greater than or equal to the parent customer.
delay_credit_days required	integer [ 0 .. 30 ] Default: 0 delay in `days` to change bank slip status from paid to creddited
contact_email required	string <email> <= 100 characters Contact email
contact_phone required	string <= 45 characters Default: null Phone email
withdrawal_min_amount_cents required	integer [ 0 .. 999999999 ] Default: 0 Minimum amount (in cents) in the account to allow a withdrawal
add_withdrawal_recurring_cron	integer [ 0 .. 1 ] Default: 0 Enum: 1 0 Enable or disable automatic daily withdrawal.
pix_key	string Pixkey, used to carry out withdrawal transactions. It can be in the format of phone, email, cpf, cnpj and random key.
address	string <= 255 characters
city	string <= 45 characters
state	string <= 20 characters
zip_code	string <= 20 characters
bank_branch_digit	string <= 45 characters It's going to be solicited for national merchants, but it's not mandatory
bank_id	string Required when the merchant is national and the `pix_key` field is empty.
bank_branch	string <= 45 characters Required when the merchant is national and the `pix_key` field is empty.
account	string <= 45 characters Required when the merchant is national and the `pix_key` field is empty.
account_type	string <= 1 characters Required when the merchant is national and the `pix_key` field is empty.
account_digit	string <= 45 characters Required when the merchant is national and the `pix_key` field is empty.
crossborder_account	string <= 255 characters Required when the merchant is international.
withdrawal_currency_id	string Required when the merchant is international.
	Array of objects[ items ] Fee by credit card paid. May be null if you do not use the product.

Responses

Request samples

Payload

Content type

application/json

{"parent_id": 3214,
"company_name": "Company Name Sub 01",
"type": "national",
"name": "Company Name Sub 01",
"legal_name": "Company Name Sub 01",
"legal_entity_number": "11222333444455",
"owner_name": "Owner Name by Sub 01",
"fee_paid_cents": 1,
"fee_dropped_cents": 1,
"fee_paid_pix_cents": 1,
"fee_dropped_pix_cents": 1,
"fee_withdrawal_cents": 0,
"fee_recipient_withdrawal_cents": 0,
"delay_credit_days": 0,
"contact_email": "my-email@domain.com.br",
"pix_key": "pix-key",
"contact_phone": "(99) 99999-9999",
"withdrawal_limit_percent": 0,
"withdrawal_min_amount_cents": 0,
"add_withdrawal_recurring_cron": 0,
"fee_credit_card": [{"installment": 1,
"fee": 1.99
},
{"installment": 2,
"fee": 2.99
}
]
}

Response samples

200

Content type

application/json

{"status": true,
"data": {"id": 3215,
"name": "Company Name Sub 01",
"wallet_uuid": "15bba482-4461-4523-8bc3-49f697756fff",
"legal_name": "Company Name Sub 01",
"owner_name": "Owner Name by Sub 01",
"legal_entity_number": "11222333444455",
"pix_key": "593c59bb-1de2-456e-8c35-e1f9432344b7",
"fee_paid_cents": 1,
"fee_dropped_cents": 1,
"fee_paid_pix_cents": 1,
"fee_dropped_pix_cents": 1,
"fee_recipient_withdrawal_cents": 0,
"fee_withdrawal_cents": 0,
"delay_credit_days": 0,
"contact_email": "my-email@domain.com.br",
"contact_phone": "(99) 99999-9999",
"active": 1,
"type": "national",
"logo": null,
"created_at": "2023-01-17 00:00:00",
"updated_at": "2023-01-17 00:00:00",
"fee_credit_card": [{"installment": 1,
"fee": 1.99
},
{"installment": 2,
"fee": 2.99
}
],
"has_advancing": 1,
"client_contract": {"id": 11,
"client_id": 666,
"withdrawal_limit_percent": 0,
"withdrawal_min_amount_cents": 0,
"withdrawal_recurring_cron": null,
"add_withdrawal_recurring_cron": 0
},
"client_notification_config": {"id": 11,
"client_id": 444,
"email_expiring_days": null,
"created_at": "2023-01-17 10:58:41",
"updated_at": "2023-01-17 10:58:41",
"deleted_at": null
}
},
"message": "Client created"
}

Get Clients or Sub-merchant

Check your client or sub-merchant registration data.

Authorizations:

bearerAuth

path Parameters

id

required

string

Your client id or sub merchant id

Responses

Response samples

200

Content type

application/json

{"status": true,
"data": {"id": 3215,
"name": "Company Name Sub 01",
"wallet_uuid": "15bba482-4461-4523-8bc3-49f697756fff",
"legal_name": "Company Name Sub 01",
"owner_name": "Owner Name by Sub 01",
"legal_entity_number": "11222333444455",
"pix_key": "593c59bb-1de2-456e-8c35-e1f9432344b7",
"fee_paid_cents": 1,
"fee_dropped_cents": 1,
"fee_paid_pix_cents": 1,
"fee_dropped_pix_cents": 1,
"fee_recipient_withdrawal_cents": 0,
"fee_withdrawal_cents": 0,
"delay_credit_days": 0,
"contact_email": "my-email@domain.com.br",
"contact_phone": "(99) 99999-9999",
"active": 1,
"type": "national",
"logo": null,
"created_at": "2023-01-17 00:00:00",
"updated_at": "2023-01-17 00:00:00",
"fee_credit_card": [{"installment": 1,
"fee": 1.99
},
{"installment": 2,
"fee": 2.99
}
],
"has_advancing": 1,
"client_contract": {"id": 11,
"client_id": 666,
"withdrawal_limit_percent": 0,
"withdrawal_min_amount_cents": 0,
"withdrawal_recurring_cron": null,
"add_withdrawal_recurring_cron": 0
},
"client_notification_config": {"id": 11,
"client_id": 444,
"email_expiring_days": null,
"created_at": "2023-01-17 10:58:41",
"updated_at": "2023-01-17 10:58:41",
"deleted_at": null
}
},
"message": "Client created"
}

Update Client or Sub-merchant

Authorizations:

bearerAuth

path Parameters

id

required

string

Your client id or sub merchant id

Request Body schema: application/json

id	integer Your client id or sub-merchant id
type required	string Enum: "national" "crossborder"
name required	string <= 255 characters Second name for your sub merchant registration. It will be shown in the reports.
legal_name required	string Legal name of your sub-merchant
legal_entity_number	string Your sub merchant's legal document
owner_name required	string <= 45 characters Name of the legal representative of the sub merchant
fee_paid_cents required	integer [ 0 .. 999999999 ] Default: null Fee in cents per paid billet. Enter null if you don't use the product, otherwise it must be greater than or equal to the parent customer.client.
fee_dropped_cents required	integer [ 0 .. 999999999 ] Default: null Fee in cents per dropped billet. Enter null if you don't use the product, otherwise it must be greater than or equal to the parent customer.
fee_paid_pix_cents required	integer [ 0 .. 999999999 ] Default: null Fee in cents per paid pix. Enter null if you don't use the product, otherwise it must be greater than or equal to the parent customer.
fee_dropped_pix_cents required	integer [ 0 .. 999999999 ] Default: null Fee in cents per dropped pix. Enter null if you don't use the product, otherwise it must be greater than or equal to the parent customer.
fee_withdrawal_cents required	integer [ 0 .. 999999999 ] Fee in cents per paid withdrawal. Enter null if you don't use the product, otherwise it must be greater than or equal to the parent customer.
fee_recipient_withdrawal_cents required	integer [ 0 .. 999999999 ] Fee in cents per withdrawal paid from recipient. Enter null if you don't use the product, otherwise it must be greater than or equal to the parent customer.
delay_credit_days required	integer [ 0 .. 30 ] Default: 0 delay in `days` to change bank slip status from paid to creddited
contact_email required	string <email> <= 100 characters Contact email
contact_phone required	string <= 45 characters Default: null Phone email
withdrawal_min_amount_cents required	integer [ 0 .. 999999999 ] Default: 0 Minimum amount (in cents) in the account to allow a withdrawal
add_withdrawal_recurring_cron	integer [ 0 .. 1 ] Default: 0 Enum: 1 0 Enable or disable automatic daily withdrawal.
bank_branch_digit	string <= 45 characters Required when the merchant is national and the `pix_key` field is empty.
bank_id	string Required when the merchant is national and the `pix_key` field is empty.
bank_branch	string Required when the merchant is national and the `pix_key` field is empty.
account_type	string Required when the merchant is national and the `pix_key` field is empty.
account_digit	string Required when the merchant is national and the `pix_key` field is empty.
pix_key	string Required when the merchant is national and when the other bank data is empty.
crossborder_account	string <= 255 characters Required when the merchant is international.
withdrawal_currency_id	string Required when the merchant is international.
address	string <= 255 characters
city	string <= 45 characters
state	string <= 20 characters
zip_code	string <= 20 characters
	Array of objects[ items ] Fee by credit card paid. May be null if you do not use the product.

Responses

Request samples

Payload

Content type

application/json

{"value": {"id": 3215,
"type": "national",
"name": "Company Name Sub 01",
"legal_name": "Company Name Sub 01",
"legal_entity_number": "11222333444455",
"owner_name": "Owner Name by Sub 01",
"fee_paid_cents": 1,
"fee_dropped_cents": 1,
"fee_paid_pix_cents": 1,
"fee_dropped_pix_cents": 1,
"fee_withdrawal_cents": 0,
"fee_recipient_withdrawal_cents": 0,
"delay_credit_days": 0,
"contact_email": "my-email@domain.com.br",
"pix_key": "pix-key",
"contact_phone": "(99) 99999-9999",
"withdrawal_limit_percent": 0,
"withdrawal_min_amount_cents": 0,
"add_withdrawal_recurring_cron": 0,
"fee_credit_card": [{"installment": 1,
"fee": 1.99
},
{"installment": 2,
"fee": 2.99
}
]
}
}

Response samples

200

Content type

application/json

{"status": true,
"data": {"id": 3215,
"name": "Company Name Sub 01",
"wallet_uuid": "15bba482-4461-4523-8bc3-49f697756fff",
"legal_name": "Company Name Sub 01",
"owner_name": "Owner Name by Sub 01",
"legal_entity_number": "11222333444455",
"pix_key": "593c59bb-1de2-456e-8c35-e1f9432344b7",
"fee_paid_cents": 1,
"fee_dropped_cents": 1,
"fee_paid_pix_cents": 1,
"fee_dropped_pix_cents": 1,
"fee_recipient_withdrawal_cents": 0,
"fee_withdrawal_cents": 0,
"delay_credit_days": 0,
"contact_email": "my-email@domain.com.br",
"contact_phone": "(99) 99999-9999",
"active": 1,
"type": "national",
"logo": null,
"created_at": "2023-01-17 00:00:00",
"updated_at": "2023-01-17 00:00:00",
"fee_credit_card": [{"installment": 1,
"fee": 1.99
},
{"installment": 2,
"fee": 2.99
}
],
"has_advancing": 1,
"client_contract": {"id": 11,
"client_id": 666,
"withdrawal_limit_percent": 0,
"withdrawal_min_amount_cents": 0,
"withdrawal_recurring_cron": null,
"add_withdrawal_recurring_cron": 0
},
"client_notification_config": {"id": 11,
"client_id": 444,
"email_expiring_days": null,
"created_at": "2023-01-17 10:58:41",
"updated_at": "2023-01-17 10:58:41",
"deleted_at": null
}
},
"message": "Client created"
}

Banks

Your GET endpoint

List of available banks

Authorizations:

bearerAuth

Responses

Response samples

200

Content type

application/json

[{"id": 999,
"name": "BANK",
"code": "999"
}
]

KYC

KYC inquiry by document

The documents that can be used in inquiries are CPF or CNPJ. The document must be sent with numbers only, without any dashes or dots. The most recent KYC for the provided document will always be returned if it exists; otherwise, an empty array will be returned.

Authorizations:

bearerAuth

path Parameters

cpf-or-cnpj

required

string

Responses

Response samples

200

Content type

application/json

{"id": 348,
"origin_request": "PAYOUT",
"description": " Compliance approved KYC without document upload",
"info_add": null,
"created_at": "2022-06-14 17:15:41",
"updated_at": "2023-10-03 16:01:28",
"merchant": "Merchant Name",
"submerchant": null,
"status": {"id": 3,
"name": "Approved"
},
"reason": {"id": 17,
"name": "Payout: Limit BRL 100K Usual"
},
"persons": [{"id": 390,
"name": "Person name",
"legal_name": null,
"document": "83562580061",
"type_person": "Beneficiary"
}
],
"document_required": [{"status": true,
"label": "Document proving the origin and destination of the operation"
},
{"status": true,
"label": "Proof of residence"
},
{"status": true,
"label": "Personal document"
},
{"status": true,
"label": "Beneficiary Full Name"
},
{"status": true,
"label": "Email"
},
{"status": true,
"label": "Phone"
},
{"status": true,
"label": "Nationality"
},
{"status": true,
"label": "Profession (Occupation)"
}
],
"documents": [{"id": 652,
"status_id": 3,
"status_name": "Approved",
"document_id": 1,
"document_name": "invoice",
"collection_name": null,
"collection_id": null,
"value_field": "https://bucket-name.s3.us-east-1.amazonaws.com/path/to/file",
"rejection_reason": null,
"label": "Document proving the origin and destination of the operation",
"type_field": "file",
"required_field": true,
"expires_at": null,
"automaticatic_validation": 0
},
{"id": 653,
"status_id": 3,
"status_name": "Approved",
"document_id": 2,
"document_name": "address",
"collection_name": null,
"collection_id": null,
"value_field": "https://bucket-name.s3.us-east-1.amazonaws.com/path/to/file",
"rejection_reason": null,
"label": "Proof of residence",
"type_field": "file",
"required_field": true,
"expires_at": null,
"automaticatic_validation": 0
},
{"id": 654,
"status_id": 3,
"status_name": "Approved",
"document_id": 3,
"document_name": "personal-document",
"collection_name": null,
"collection_id": null,
"value_field": "https://bucket-name.s3.us-east-1.amazonaws.com/path/to/file",
"rejection_reason": null,
"label": "Personal document",
"type_field": "file",
"required_field": true,
"expires_at": null,
"automaticatic_validation": 0
},
{"id": 655,
"status_id": 3,
"status_name": "Approved",
"document_id": 5,
"document_name": "full-name-beneficiary",
"collection_name": null,
"collection_id": null,
"value_field": null,
"rejection_reason": null,
"label": "Beneficiary Full Name",
"type_field": "text",
"required_field": true,
"expires_at": null,
"automaticatic_validation": 0
},
{"id": 656,
"status_id": 3,
"status_name": "Approved",
"document_id": 7,
"document_name": "email",
"collection_name": null,
"collection_id": null,
"value_field": null,
"rejection_reason": null,
"label": "Email",
"type_field": "text",
"required_field": true,
"expires_at": null,
"automaticatic_validation": 0
},
{"id": 657,
"status_id": 3,
"status_name": "Approved",
"document_id": 8,
"document_name": "phone",
"collection_name": null,
"collection_id": null,
"value_field": null,
"rejection_reason": null,
"label": "Phone",
"type_field": "text",
"required_field": true,
"expires_at": null,
"automaticatic_validation": 0
},
{"id": 658,
"status_id": 3,
"status_name": "Approved",
"document_id": 11,
"document_name": "nationality",
"collection_name": null,
"collection_id": null,
"value_field": null,
"rejection_reason": null,
"label": "Nationality",
"type_field": "text",
"required_field": true,
"expires_at": null,
"automaticatic_validation": 0
},
{"id": 659,
"status_id": 3,
"status_name": "Approved",
"document_id": 9,
"document_name": "profession",
"collection_name": null,
"collection_id": null,
"value_field": null,
"rejection_reason": null,
"label": "Profession (Occupation)",
"type_field": "text",
"required_field": true,
"expires_at": null,
"automaticatic_validation": 0
}
],
"early_kyc_ids": [ ]
}

Send cbd documents

Attention points

Supported extensions: jpg, jpeg, gif, png and pdf
The maximum size of all files added together is: 10mb
The field codigo_rastreio_transportadora can have a maximum of 255 characters

Authorizations:

bearerAuth

path Parameters

payinId

required

string

Payin ID

Request Body schema: multipart/form-data

fatura	any
autorizacao_anvisa	any
receituario_medico	any
personal_document	any
codigo_rastreio_transportadora	string

Responses

Response samples

200
400
422

Content type

application/json

{"fatura": "string",
"autorizacao_anvisa": "string",
"receituario_medico": "string",
"personal_document": "string",
"codigo_rastreio_transportadora": "string"
}

Submit a document for KYC

This route is used to submit documents for a pending KYC. There are two types of documents that can be submitted:

Text-type documents
File-type documents

Only one document can be updated at a time.

Attention point

Supported extensions for file-type documents : jpg, jpeg, gif, png and pdf

Authorizations:

bearerAuth

path Parameters

documentId

required

string

Request Body schema:
application/json
application/json
multipart/form-data

value

required

string <= 250 characters

Responses

Request samples

Payload

Content type

{"value": "test"
}

Response samples

200

Content type

application/json

{"id": 5891,
"status_id": 2,
"status_name": "Waiting Approval Documents",
"document_id": 35,
"document_name": "kyc/qsa",
"collection_name": null,
"collection_id": null,
"value_field": "https://s3.amazonaws.com/bucket-name/path/to/file",
"rejection_reason": null,
"label": "KYC/QSA",
"type_field": "file",
"required_field": true,
"expires_at": null,
"automaticatic_validation": 0
}

Transactions

List all your transactions

Authorizations:

bearerAuth

path Parameters

clientId

required

string

Client ID

query Parameters

id	any Unique identifier of the transaction.
entity	any The entity associated with the transaction.
impacted_balance	any Specifies whether the transaction impacted the account balance (e.g., "a", "b" or "ab").
page	any The current page of results to retrieve in a paginated response.
per_page	any The number of items to display per page in a paginated response.
created_after	any Filter to include transactions created after the specified date.
created_before	any Filter to include transactions created before the specified date.
entity_id	any Unique identifier of the entity associated with the transaction.

Responses

Response samples

200

Content type

application/json

[{"id": 0,
"amount_cents": 0,
"available_balance_cents": 0,
"balance_cents": 0,
"reserve_balance_cents": 0,
"description": "string",
"entity": "string",
"entity_id": 0,
"impacted_balance": "string",
"created_at": "string"
}
]