Skip to main content

Person

All pay-in and pay-out transactions within Attrus must be associated with a customer, either a person or a company. This ensures that their internal ID, called subject_id, can be used as a reference for future transactions

Required information for person registration

The following endpoint is used to register person customers, regardless of nationality. If a document number has been previously registered, the person's details will be updated. As soon as you send the request to register the customer, you will receive a response with their subject_id.

Customer Registration

curl -X POST "https://api.facilitapay.com/api/v1/subject/people" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
-d '{
"person": {
"document_number": "70590071050",
"document_type": "cpf",
"social_name": "Joaquim dos Santos",
"email": "[email protected]",
"phone_country_code": "55",
"phone_area_code": "18",
"phone_number": "99812-1212",
"birth_date": "2015-04-01",
"net_monthly_average_income": "4000",
"address_street": "Rua Barão do Rio Branco",
"address_number": "310",
"address_complement": "Apt. 44 A",
"address_postal_code": "16201220",
"address_city": "Birigui",
"address_state": "SP",
"address_country": "Brasil",
"fiscal_country": "Brasil",
"documents": [
{
"file_type": "application/pdf",
"file_url": "http://somedomain.com/document-x.pdf",
"labels": [
"person-cpf"
]
}
]
}
}'
{
"data": {
"updated_at": "2025-07-09T13:51:30.989491",
"status": "approved",
"social_name": "Joaquim dos Santos",
"rfc_pf": null,
"required_clearance_level": 1,
"references": [],
"phone_number": null,
"phone_country_code": null,
"phone_area_code": null,
"net_monthly_average_income": null,
"inserted_at": "2023-12-11T14:11:02.571103",
"id": "5fd0aa81-b427-4a29-9968-6491d1d7f8b0",
"fiscal_country": "Brasil",
"email": null,
"documents": [],
"document_type": "cpf",
"document_number": "70590071050",
"clearance_level": 1,
"birth_date": null,
"address_street": null,
"address_state": null,
"address_postal_code": null,
"address_number": null,
"address_neighborhood": null,
"address_country": null,
"address_complement": null,
"address_city": null
}
}
warning

Common mistakes

Please provide a valid document number without dots or dashes. This field is validated when using all document types accepted by the API (cpf, curp, cc, ce, rut, passport) as the document type. As some example, you can generate a valid CPF using this website. You can also create a valid CURP/RFC document number using thisother website

HTTP Request

POST /subject/people

Body Parameters

ParameterDescriptionTypeRequiredRequired For
personAn object containing all the required valuesobjecttrue
document_numberCustomer's national document numberstringtrueAll transactions
document_typeCustomer's type of document (cpf, curp, cc, ce, rut, passport)stringtrueAll transactions
social_nameCustomer's full social namestringtrueAll transactions
fiscal_countryCustomer's fiscal countrystringtrueAll transactions
emailCustomer's emailstringfalseAll Cards, PSE and Boleto transactions
websiteCustomer's website or related profile pagestringfalse
phone_country_codeCountry phones code (2 digits: BR +55; MX +52; CO +57; CL +52)stringfalseAll cards transactions in MXN and for PSE
phone_area_codeInternal country area codestringfalsePSE transactions
phone_numberCustomer's phone numberstringfalseAll Cards, PSE and Boleto transactions
birth_dateCustomer's birth datestringfalse
net_monthly_average_incomeCustomer's monthly average incomestringfalse
address_streetCustomer's street namestringfalseAll cards, PSE and boleto transactions
address_numberCustomer's house numberstringfalseAll cards, PSE and boleto transactions
address_complementCustomer's block or apartmentstringfalse
address_neighborhoodCustomer's neighborhood/districtstringfalseAll cards, PSE and boleto transactions
address_postal_codePostal/zip code.stringfalseAll cards, PSE and boleto transactions
address_cityCustomer's city namestringfalseAll cards, PSE and boleto transactions
address_stateCustomer's state of residence. In Brazil you'll use only 2 letters : AC, AL, AP, AM, BA, CE, DF, ES, GO, MA, MT, MS, MG, PA, PB, PR, PE, PI, RJ, RN, RS, RO, RR, SC, SP, SE, TO.stringfalseAll cards, PSE and boleto transactions
address_countryCustomer's country of residencestringfalseAll cards, PSE and boleto transactions
documentsAn array of documents related to the Customer (Customers who operate above a threshold value per month or exceed a cumulative limit in the last 12 months of operation must have the following associated documents: rg-number, cpf-number, rg-photo, address-proof, revenue-tax-declaration).arrayfalseCustomers who exceeds 20k USD annually in their amount of transactions
documents.labelsKeywords that may help identify the document in the person registration tab.arrayfalseWhen sending documents field
documents.file_typeDocument file MIME type. Must match the document type.stringfalseWhen sending documents field
documents.file_dataDocument file encoded in Base64.stringfalseWhen sending documents and using the file_data
documents.file_nameThe name of the file to be stored. Any file extension is accepted, but the extension must be included. Ex: document.pdf, document.docx, report.xlsstringfalseWhen sending documents field and using the file_data
documents.file_urlPublic URL pointing to the document. Note that it must start with http:// or https://stringfalseWhen sending documents and using a URL

Brazilian Person Registration

Request

curl -X POST "https://api.facilitapay.com/api/v1/subject/people" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
-d '{
"person": {
"document_number": "70590071050",
"document_type": "cpf",
"social_name": "Joaquim dos Santos",
"fiscal_country": "Brasil"
}
}'
201Created
{
"data": {
"updated_at": "2025-07-09T13:51:30.989491",
"status": "approved",
"social_name": "Joaquim dos Santos",
"rfc_pf": null,
"required_clearance_level": 1,
"references": [],
"phone_number": null,
"phone_country_code": null,
"phone_area_code": null,
"net_monthly_average_income": null,
"inserted_at": "2023-12-11T14:11:02.571103",
"id": "5fd0aa81-b427-4a29-9968-6491d1d7f8b0",
"fiscal_country": "Brasil",
"email": null,
"documents": [],
"document_type": "cpf",
"document_number": "70590071050",
"clearance_level": 1,
"birth_date": null,
"address_street": null,
"address_state": null,
"address_postal_code": null,
"address_number": null,
"address_neighborhood": null,
"address_country": null,
"address_complement": null,
"address_city": null
}
}

For Brazil, the document_type is usually the CPF (a 11 digit-number), below you can check a payload sample for registration of a person in Brazil. For other requirements depending on payment methods, check the table Required information for person registration

HTTP Request

POST /subject/people

Body Parameters

See person body properties

Mexican Person Registration

Request

curl -X POST "https://api.facilitapay.com/api/v1/subject/people" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
-d '{
"person": {
"document_number": "SOMH031031HSRTRR04",
"document_type": "curp",
"social_name": "Horacio Soto Morales",
"fiscal_country": "Mexico",
"rfc_pf": "SOMH031031C50"
}
}'
{
"data": {
"updated_at": "2023-08-07T20:50:54.920150",
"status": "approved",
"social_name": "Horacio Soto Morales",
"required_clearance_level": 1,
"references": [],
"phone_number": null,
"net_monthly_average_income": null,
"inserted_at": "2023-07-20T13:33:08.286343",
"id": "9fc9ad01-1b1f-466e-b50d-51cdc46fab8b",
"fiscal_country": "Mexico",
"rfc_pf": "SOMH031031C50",
"email": null,
"documents": [],
"document_type": "curp",
"document_number": "SOMH031031HSRTRR04",
"clearance_level": 1,
"birth_date": null,
"address_street": null,
"address_state": null,
"address_postal_code": null,
"address_number": null,
"address_country": null,
"address_complement": null,
"address_city": null
}
}

In Mexico you will need to register a CURP (18 digits) and, if you have one, an RFC (13 digits). This way, once the payment is received and the documents are identified, we can process it. Below you can see a payload with the initial information required. For other requirements, depending on the payment method, see the table Required information for person registration

HTTP Request

POST /subject/people

Body Parameters

See person body properties

warning

Common mistakes

If you are registering a customer with both CURP and RFC_PF, the first 10 digits of these identifiers must match. If they do not, this error will be returned. You can generate a fake CURP and RFC for tests using this link: "https://datafakegenerator.com/genrfc".

Colombian Person Registration

Request

curl -X POST "https://api.facilitapay.com/api/v1/subject/people" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
-d '{
"person": {
"document_number": "1037633286",
"document_type": "cc",
"social_name": "Pablo Castro",
"fiscal_country": "Colombia"
}
}'
200OK
{
"data": {
"updated_at": "2023-09-26T20:55:55.900000",
"status": "approved",
"social_name": "Pablo Castro",
"required_clearance_level": 1,
"references": [],
"phone_number": null,
"net_monthly_average_income": null,
"inserted_at": "2023-07-20T13:33:08.286343",
"id": "9fc9ad01-1b1f-466e-b50d-51cdc46fab8b",
"fiscal_country": "Colombia",
"email": null,
"documents": [],
"document_type": "cc",
"document_number": "1037633286",
"clearance_level": 1,
"birth_date": null,
"address_street": null,
"address_state": null,
"address_postal_code": null,
"address_number": null,
"address_country": null,
"address_complement": null,
"address_city": null
}
}

In Colombia, the document_type will be put like "cc" (Cedula de Ciudadania - natural citizens, a 10-digit number) or "ce" (Cedula de Extranjeria - for foreign citizens, a 6 to 9-digit number). Below you can check a payload with initial required information. For other requirements depending on payment methods, check the table Required information for person registration

HTTP Request

POST /subject/people

Body Parameters

See person body properties

Chilean Person Registration

Request

curl -X POST "https://api.facilitapay.com/api/v1/subject/people" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
-d '{
"person": {
"document_number": "173243421",
"document_type": "rut",
"social_name": "Marcela Carolina",
"fiscal_country": "Chile"
}
}'
200OK
{
"data": {
"updated_at": "2025-01-31TT13:33:08.286377",
"status": "approved",
"social_name": "Marcela Carolina",
"required_clearance_level": 1,
"references": [],
"phone_number": null,
"net_monthly_average_income": null,
"inserted_at": "2025-01-31T13:33:08.286343",
"id": "9fc9ad01-1b1f-466e-b50d-51cdc46fab8b",
"fiscal_country": "Chile",
"email": null,
"documents": [],
"document_type": "rut",
"document_number": "173243421",
"clearance_level": 1,
"birth_date": null,
"address_street": null,
"address_state": null,
"address_postal_code": null,
"address_number": null,
"address_country": null,
"address_complement": null,
"address_city": null
}
}

In Chile, the document_type will be "rut" (Rol Unico Tributario, a 9-digit number). Below you can check a payload with initial required information. For other requirements depending on payment methods, check the table Required information for person registration

HTTP Request

POST /subject/people

Body Parameters

See person body properties

Person List

Request

curl -X GET "https://api.facilitapay.com/api/v1/subject/people" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...."
200OK
{
"data": [
{
"updated_at": "2021-03-25T18:32:54.448951",
"status": "approved",
"social_name": "Mauricio Silva",
"required_clearance_level": 1,
"references": [],
"phone_number": "99123-2313",
"net_monthly_average_income": "1000.00",
"inserted_at": "2021-03-13T02:05:34.206799",
"id": "0be2c99a-bb6e-4a1f-97a5-5eeaff0671c8",
"fiscal_country": "Brasil",
"email": "[email protected]",
"documents": [
{
"labels": [
"rg-number",
"cpf-number",
"rg-photo"
],
"id": "58ca9984-3cb8-4462-97a6-0b2f7776ed24",
"file_url": "http://somedomain.com/files/driverslicense.jpg",
"file_type": "image/jpeg"
},
{
"labels": [
"address-proof"
],
"id": "5d2cce7a-3814-4baf-a1b5-077db9d3bdf7",
"file_url": "http://somedomain.com/files/doc.pdf",
"file_type": "application/pdf"
}
],
"document_type": "cpf",
"document_number": "24189952087",
"clearance_level": 1,
"birth_date": "1990-12-03",
"address_street": "Rua Presidente Wenceslau",
"address_state": "SP",
"address_postal_code": "13090509",
"address_number": "708",
"address_country": "BR",
"address_complement": "Jardim Pres. Wenceslau",
"address_city": "Campinas"
}
]
}

You can list the customers already registered, using the following endpoint. Note that the API has a limit of 100 for each request.

HTTP Request

GET /subject/people

Path Parameters

ParameterDescriptionTypeRequired
last_idLast customer UUID for paginationstringfalse

Person Update

Request

curl -X PUT "https://api.facilitapay.com/api/v1/subject/people/5fd0aa81-b427-4a29-9968-6491d1d7f8b0" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
-d '{
"person": {
"net_monthly_average_income": "2000"
}
}'
{
"data": {
"updated_at": "2025-07-09T13:51:30.989491",
"status": "approved",
"social_name": "Joaquim dos Santos",
"rfc_pf": null,
"required_clearance_level": 1,
"references": [],
"phone_number": null,
"phone_country_code": null,
"phone_area_code": null,
"net_monthly_average_income": "2000",
"inserted_at": "2023-12-11T14:11:02.571103",
"id": "5fd0aa81-b427-4a29-9968-6491d1d7f8b0",
"fiscal_country": "Brasil",
"email": "[email protected]",
"documents": [],
"document_type": "cpf",
"document_number": "70590071050",
"clearance_level": 1,
"birth_date": null,
"address_street": null,
"address_state": null,
"address_postal_code": null,
"address_number": null,
"address_neighborhood": null,
"address_country": null,
"address_complement": null,
"address_city": null
}
}
warning

Common mistakes

It is not possible to update the document_number and document_type.

To update a person's information, you can use the endpoint below:

Note: You can update all fields except for document_number and document_type. There is no need to send fields that are not being updated.

HTTP Request

PUT /subject/people/:id

Path Parameters

ParameterDescriptionTypeRequired
idPerson's UUIDstringtrue

Body Parameters

See person body properties

Person Details

Request

curl -X GET "https://api.facilitapay.com/api/v1/subject/people/ba70edd2-2210-40de-aa14-2e8efa1416f2" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...."
200OK
{
"data": {
"updated_at": "2021-03-08T22:32:04.515724",
"status": "approved",
"social_name": "Joaquin Teixeira dos Antos",
"required_clearance_level": 1,
"references": [],
"phone_number": "98989-8989",
"net_monthly_average_income": "3000.00",
"inserted_at": "2021-03-08T22:32:04.475951",
"id": "ba70edd2-2210-40de-aa14-2e8efa1416f2",
"fiscal_country": "Brasil",
"email": "[email protected]",
"documents": [
{
"labels": [
"person-photo"
],
"id": "1c130b69-fb92-4420-aa68-f442703510d0",
"file_url": "https://onedrive.com/files/document-z.pdf",
"file_type": "application/pdf"
}
],
"document_type": "passport",
"document_number": "5079865",
"clearance_level": 1,
"birth_date": "1991-01-01",
"address_street": "Rua Barão do Rio Branco",
"address_state": "MG",
"address_postal_code": "33405938",
"address_number": "670",
"address_country": "BR",
"address_complement": "Apt. 1802",
"address_city": "Divinópolis"
}
}

To check a person's information, you can use the following endpoint:

HTTP Request

GET /subject/people/:id

Path Parameters

ParameterDescriptionTypeRequired
idPerson UUIDstringtrue

Customer KYC and upload of documents

Webhook

{
"data": {
"updated_at": "2023-03-17T18:27:39.671478",
"status": "reproved",
"social_name": "Luiz Abreu Neto",
"required_clearance_level": 2,
"references": [],
"phone_number": "119999999999",
"net_monthly_average_income": "7000.00",
"id": "a7e3346b-f6fd-4380-bbfc-c6fc51507820",
"fiscal_country": "Brasil",
"email": "[email protected]",
"documents": [],
"document_type": "cpf",
"document_number": "61558254676",
"clearance_level": 1,
"birth_date": "1990-10-10"
}
}

All new customers are initially registered and approved as level 1, even when no documentation is provided in the first registration.

After the customer reaches the limit of 20k USD transacted annually, if any mandatory document is missing, the next payment he'll do will have the flag cleared=false, and a webhook will be sent to you with the documents needed to be uploaded – you can check this section for more information.

Below are the status and how a reproved customer that has not sent his documents for analysis is shown. If money is sent from/to this customer, the transaction will remain on hold (cleared = false) until it is approved again.

PropertyContent
approvedCustomer is able to send/receive money through the platform. No action is needed on your side.
reprovedCustomer is required to send documents for review, or it had already been sent but it had been rejected by KYC, in this case you will need to provide new ones.
waiting_approvalCustomer has sent the KYC documents but is waiting for the analysis from the backoffice. No action is needed on your side.

Before reaching this stage and receiving the webhook, you can check the amount transacted for that specific subject_id in local currency, as well as the number of transactions. You can use the following endpoint to get this information and ask for the documents in advance.

Get transactions for subject

Get the transactions for that specific subject_id in local currency.

Request

curl -X GET "https://api.facilitapay.com/api/v1/subject/21d90105-5bcb-465c-8c1d-8a2cb8339ecd/transactions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...."
200OK
{
"data": [
{
"value": "2500.00",
"to_bank_account_id": "b51dff12-071f-486d-9667-9f3295186e3b",
"subject_is_receiver": false,
"status": "identified",
"source_name": "Gustavo Maia",
"source_document_type": "cpf",
"source_document_number": "10000000019",
"short_id": "AF9DCA5E",
"meta": {
"some_external_transaction_id": "TPUP000000894089"
},
"inserted_at": "2022-03-08T13:03:20.920784",
"id": "21d90105-5bcb-465c-8c1d-8a2cb8339ecd",
"from_credit_card_id": null,
"from_bank_account_id": "912fccae-d4db-4416-8b44-4e7abb8a47e2",
"for_exchange": true,
"exchange_under_request": false,
"exchange_currency": "USD",
"estimated_value_until_exchange": false,
"currency": "BRL",
"cleared": false,
"bank_transaction": {
"wire_id": null,
"value": "2500.0",
"source_type": "TED-PRE",
"source_name": "Gustavo Maia",
"source_id": "21d90105-5bcb-465c-8c1d-8a2cb8339ecd",
"source_document_type": "cpf",
"source_document_number": "10000000019",
"source_description": "CREDITO POR TED ANTECIPADO",
"source_branch": null,
"source_bank": null,
"source_account": null,
"movement_date": "2022-03-08",
"iof_value": null,
"inserted_at": "2022-03-08T13:03:21.037379",
"id": "3c113e72-f882-4dd1-b0c5-b4500f9abe2c",
"exchanged_value": null,
"exchange_rate": null,
"exchange_id": null,
"exchange_currency": "USD",
"exchange_approved": false,
"currency": "BRL"
}
}
]
}

HTTP Request

GET /subject/:id/transactions

Path Parameters

ParameterDescriptionTypeRequired
idCustomer's UUIDstringtrue

Get transacted value for subject

Get the total transactions value for that specific subject_id.

Request

curl -X GET "https://api.facilitapay.com/api/v1/subject/21d90105-5bcb-465c-8c1d-8a2cb8339ecd/transaction_values" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...."
200OK
{
"data": [
{
"value": "30111.00",
"exchanged_value": "5660.97",
"exchange_currency": "USD",
"currency": "BRL",
"count": 7
}
]
}

HTTP Request

GET /subject/:id/transaction_values

Path Parameters

ParameterDescriptionTypeRequired
idCustomer's UUIDstringtrue

Upload subject documents

Request using a file

curl -X POST "https://api.facilitapay.com/api/v1/subject/5fd0aa81-b427-4a29-9968-6491d1d7f8b0/documents" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
-d '{
"document": {
"labels": [
"rg-number",
"cpf-number",
"rg-photo"
],
"file_data": "Base64-encoded-string",
"file_type": "application/pdf",
"file_name": "document.pdf"
}
}'

Request using an URL

curl -X POST "https://api.facilitapay.com/api/v1/subject/5fd0aa81-b427-4a29-9968-6491d1d7f8b0/documents" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
-d '{
"document": {
"labels": [
"rg-number",
"cpf-number",
"rg-photo"
],
"file_url": "https://www.rearden.co.us/files/47358347534875.jpeg",
"file_type": "image/jpeg"
}
}'
{
"data": {
"labels": [
"rg-number",
"cpf-number",
"rg-photo"
],
"id": "b258d5e5-8959-4aa5-b146-05c3b3366ba8",
"file_url": "https://www.rearden.co.us/files/47358347534875.jpeg",
"file_type": "image/jpeg"
}
}
warning

Common mistakes

This error typically occurs when:

  • The file_name field is missing or does not include the file extension (e.g., document.pdf, report.docx)
  • The file_data is not properly encoded in Base64
  • The file_type MIME type does not match the actual file content

Solution: Ensure the file_name field includes the correct file extension and that the file_data is properly Base64 encoded.

400 - Bad Request

  • Make sure all required fields are present in your request.

When sending the documents required, you can use the following endpoint. You can also send, list and show details of the documents related to that specific subject_id. There are two possible ways to send us the documents: by URL or by file (Base64 encoded, no more than 15MB per file).

Customer Approval

HTTP Request

POST /subject/:id/documents

Path Parameters

ParameterDescriptionTypeRequired
idCustomer's UUIDstringtrue

Body Parameters

ParameterDescriptionTypeRequiredRequired For
documentAn array of documents related to the Customerarraytrue
labelsLabels that will help describe the document.arraytruePayload using file_data and URL
file_typeDocument file MIME type. Must match the document type.stringtruePayload using file_data and URL
file_dataDocument file encoded in Base64.stringfalsePayload using file_data
file_nameThe name of the file to be stored. Any file extension is accepted, but the extension must be included. Ex: document.pdf, document.docx, report.xlsstringfalseWhen using sending file_data
file_urlURL to your imagestringfalsePayload using URL