Webhooks

Webhooks are notifications triggered upon event changes that take place in our platform. There are webhooks for both customer and transactions events. They will be sent to the registered URL. If your host is not available at the time, there will be 5 other attempts, spaced in an increasingly interval.

Enable and disable webhooks

curl -X POST "https://api.facilitapay.com/api/v1/enable_webhooks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
  -d '{
  "url": "https://your-url-for-listening-to-webhooks.com"
}'

200OK

{
  "data": {
    "secret": "3718"
  }
}

For enabling a webhook, you'll need to register your own URL to receive notifications from Attrus. You can use the following endpoint to enable the webhooks:

After registering, you'll receive a secret, a value that will be posted along with the notification information for authenticity check. See the sample below:

HTTP Request

POST /enable_webhooks

Body Parameters

Parameter	Description	Type	Required
`url`	Url to receive notifications from the api	string	true

Disable Webhooks

curl -X GET "https://api.facilitapay.com/api/v1/disable_webhooks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...."

200OK

{
  "data": "ok"
}

If you want to disable all notifications, just make a request using the endpoint below:

HTTP Request

GET /disable_webhooks

Listing sent notifications

If you want to get a list of all the notifications sent by us, you can use the following endpoint for it. You can also use some filters for it, to search only for the failed ones, or by date.

Example: You can use the endpoint /notifications?last_id=a5c69e9e-8d84-4b0b-9af8-dcfb5be35093&per_page=1.

This will return the last notifications after the notifications with ID a5c69e9e-8d84-4b0b-9af8-dcfb5be35093.

curl -X GET "https://api.facilitapay.com/api/v1/notifications" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...."

200OK

{
  "data": [{
    "url": "https://webhook.site/8efeee1c-8d3d-4d41-95ff-cc2ffb042f4b",
    "sent_at": null,
    "notification": {
      "type": "payment_failed",
      "transaction_id": "173e30f4-9956-4e86-8fc0-d27b125a8678"
    },
    "inserted_at": "2022-09-19T16:21:15.100177",
    "id": "58215ec6-8f2b-40d4-9e50-c790ace92957",
    "failed_at": "2022-09-19T16:21:15.100177"
  }]
}

HTTP Request

GET /notifications

Query Parameters

Parameter	Description	Type	Required
`last_id`	Id of the last webhook to be excluded from the results	string	false
`per_page`	Quantity of results to limit the search	string	false
`order_by`	Order by date. Default ordering is ascending (older notifications first). Use `desc` to order from the newest notifications	string	false
`failed`	List only failed or successful webhooks. Ignoring this parameter will list both statuses	boolean	false

Marking notifications as received

If, for any reason, your server fails to receive a webhook, the notification will be marked as failed at that time. You can filter these failed notifications by using the failed=true query parameter with the endpoint above.

After processing them, you can use their respective IDs to mark each notification as successful via the endpoint provided below.

curl -X PUT "https://api.facilitapay.com/api/v1/notifications/:id" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...."

200OK

{
  "data": {
    "url": "https://webhook.site/8efeee1c-8d3d-4d41-95ff-cc2ffb042f4b",
    "sent_at": null,
    "notification": {
      "type": "payment_failed",
      "transaction_id": "173e30f4-9956-4e86-8fc0-d27b125a8678"
    },
    "inserted_at": "2022-09-19T16:21:15.100177",
    "id": "58215ec6-8f2b-40d4-9e50-c790ace92957",
    "failed_at": null
  }
}

HTTP Request

PUT /notifications/:id

Path Parameters

Parameter	Description	Type	Required
`id`	UUID of the webhook/notification	string	true

Webhooks for transactions

Identified transaction

{
  "notification": {
    "type": "identified",
    "transaction_id": "UUID",
    "secret": "the value you received"
  }
}

We always send webhook notifications for all transactions whenever there is a status change. This webhook will always be the first notification you receive — assuming everything goes as expected. It is triggered when the incoming funds are received in the Attrus bank account created exclusively for your use, or when there is sufficient available balance to initiate a transaction such as payouts or conversions between internal accounts.

Exchange created for transaction

{
  "notification": {
    "type": "exchange_created",
    "exchange_id": "some_uuid",
    "transaction_ids": [
      "transaction-id-a",
      "transaction-id-b"
    ],
    "secret": "the value you received"
  }
}

If the transaction involves a currency conversion, this webhook will be triggered after the previous one (type: identified). It will be sent either once the exchange has been successfully created by our operations team, or automatically right after the identified notification if you have automatic exchange enabled.

Note that a single exchange can be associated with multiple transactions if they share the same subject and destination account. For this reason, you will receive a list of transaction IDs in the transaction_ids field.

Wire created

{
  "notification": {
    "type": "wire_created",
    "wire_id": "some_uuid",
    "transaction_ids": [
      "transaction-id-a",
      "transaction-id-b"
    ],
    "secret": "the value you received"
  }
}

Once the funds leave Attrus environment to complete a transaction — such as a payout or a requested settlement — this webhook will be triggered to notify you that the wire has been completed. In short, it means the funds have already been sent either to your customer's bank account or to your international bank account.

Note that a single wire transfer can be associated with multiple transactions if they share the same subject and destination account. For this reason, you will receive a list of transaction IDs in the transaction_ids field.

Example: You need to send money to your customer and create two transactions using the same destination bank account. Instead of sending the funds separately, we will group them and send a single wire with the total amount of both transactions combined.

Approved card transaction

{
  "notification": {
    "type": "payment_approved",
    "transaction_id": "bfb7a294-89ad-4a9e-a221-5e9c499a05f0",
    "checkout_id": "80c675cc-5a68-4023-87a3-faf13401d424",
    "secret": "the value you received"
  }
}

We also have specific webhooks for card related transactions. This webhook will be triggered when a card payment has been approved for a card transaction:

Parameters

Parameter	Description	Type	Required
`notification`	An object containing all the required values	object	true
`type`	Type of the notification. In this case, it will always be `payment_approved`	string	true
`transaction_id`	ID of the transaction	string	true
`checkout_id`	ID of the checkout page. It will only be sent if the transaction was created using the checkout page API	string	false
`secret`	The secret you set when you register your webhook by using the `Enabling webhooks` endpoint	string	true

Reproved card transaction

If a card payment is not approved, the following webhook will be sent. Note that if the checkout page API is being used, this webhook will be triggered for every failed payment attempt. The transaction ID will differ with each attempt, while the checkout ID will remain the same.

{
  "notification": {
    "type": "payment_failed",
    "transaction_id": "bfb7a294-89ad-4a9e-a221-5e9c499a05f0",
    "checkout_id": "80c675cc-5a68-4023-87a3-faf13401d424",
    "secret": "the value you received"
  }
}

Parameters

Parameter	Description	Type	Required
`notification`	An object containing all the required values	object	true
`type`	Type of the notification. In this case, it will always be `payment_failed`	string	true
`transaction_id`	ID of the transaction	string	true
`checkout_id`	ID of the checkout page. It will only be sent if the transaction was created using the checkout page API	string	false
`secret`	The secret you set when you register your webhook by using the `Enabling webhooks` endpoint	string	true

Request for wire correction

When Attrus can't process a payment due to receiver account information errors, such as incorrect branch or account number, the API will send a wire_waiting_correction. To correct the bank account details, you must send a request to update it using the endpoint in the sequence below.

{
  "notification": {
    "error_code": "AC03",
    "error_description": "Creditor account number invalid or missing",
    "secret": "8958",
    "bank_account_owner_id": "person-UUID",
    "bank_account_id": "bank-account-UUID",
    "transaction_ids": [
      "transaction-UUID"
    ],
    "type": "wire_waiting_correction",
    "wire_id": "wire-UUID"
  }
}

Error Codes

Error Code	Description
`AC03`	Creditor account number invalid or missing (`branch_number` or `account_number` incorrect)
`AC14`	Creditor account type missing or invalid (`account_type` incorrect)
`CH11`	Value in Creditor Identifier is incorrect (`owner_document_number` incorrect)
`AG03`	Transaction type not supported/authorized on this account (account rejected the payment)

Sending the correct bank account details for wire

curl -X PUT "https://api.facilitapay.com/api/v1/wires/:id/update_bank_account" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
  -d '{
  "bank_account": {
    "currency": "BRL",
    "bank": {"code": "260","name": "Nu Pagamentos S.A."},
    "branch_number": "1",
    "account_number": "36725089",
    "owner_document_number": "Person name",
    "owner_name": "Person name",
    "branch_country": "BR",
    "account_type": "conta-corrente"
  }
}'

Once you get the correct bank account information from the customer you must send a request to update it using the following endpoint, so the API will then try again. If it succeeds, the API sends the wire_created webhook.

200OK

{
  "currency": "BRL",
  "id": "51ca5a65-bbd2-433d-8527-1cb36bf4a1c2",
  "inserted_at": "2025-07-10T18:39:43.580056",
  "status": "waiting_confirmation",
  "to_bank_account": {
    "aba": null,
    "account_number": "456",
    "account_type": "conta-corrente",
    "bank": {
      "code": "012",
      "country": "BRA",
      "id": "04bf9dc2-f189-4a1f-929d-5478def064e9",
      "ispb": "04866275",
      "name": "Banco Inbursa S.A.",
      "swift": null
    },
    "branch_country": "BRA",
    "branch_number": "8221",
    "company": {
      "company_name": "Subject",
      "document_number": "67645727390",
      "document_type": "cpf",
      "fiscal_country": "BR",
      "id": "31288cc8-e106-4aec-8437-85758ba671c0",
      "phone_number": null,
      "social_name": "Subject"
    },
    "currency": "BRL",
    "iban": null,
    "id": "79247afc-b15d-441c-af72-08f2013fd58e",
    "intermediary_bank_account": null,
    "nickname": null,
    "owner_document_number": "67645727390",
    "owner_document_type": null,
    "owner_name": "Subject",
    "pix_info": null,
    "routing_number": null
  },
  "unretryable": false,
  "value": "500.0"
}

HTTP Request

PUT /wires/:id/update_bank_account

Account Type Values

Value	Description
`conta-corrente`	Checking account
`poupanca`	Savings account

Webhooks for subscriptions

We always send webhook notifications for all subscriptions whenever there is a status change. This section describes the webhooks for subscriptions.

Subscription activated

{
  "notification": {
    "secret": "the value you received",
    "type": "subscription_activated",
    "subscription": {
      "id": "e97e7ad9-3cfc-4701-8a4f-77eaa9402b35",
      "status": "active",
      "subject_id": "e0e34575-bee4-423d-a989-cfd525b965cf"
    }
  }
}

This notification is sent when the subscription is activated, meaning that the first invoice has been successfully processed and the subscription is now active.

Subscription canceled

This webhook is triggered whenever a subscription is canceled, either by the merchant via API or by the payer. The field canceled_by_payer indicates whether the cancellation was initiated by the payer (true) or by the merchant (false).

{
  "notification": {
    "secret": "the value you received",
    "type": "subscription_canceled",
    "subscription": {
      "canceled_by_payer": false,
      "canceled_reason": "some reason",
      "id": "7de0dc6f-f514-4401-84f3-ff19183e6b92",
      "status": "canceled",
      "subject_id": "76d5aea7-f532-47be-9cfb-b1f615c7bc84"
    }
  }
}

Subscription is complete

{
  "notification": {
    "secret": "the value you received",
    "type": "subscription_completed",
    "subscription": {
      "id": "7de0dc6f-f514-4401-84f3-ff19183e6b92",
      "status": "completed",
      "subject_id": "76d5aea7-f532-47be-9cfb-b1f615c7bc84"
    }
  }
}

This webhook is triggered when a subscription completes its full lifecycle — meaning all cycles have been processed and every related invoice has been successfully paid.

Invoice paid

This notification is send when an invoice related to a subscription is paid.

{
  "notification": {
    "secret": "the value you received",
    "type": "invoice_paid",
    "invoice": {
      "id": "d5dbfff5-7391-447b-a642-a57af80b09db",
      "status": "paid",
      "subject_id": "7c6afdd6-eb4b-4113-93c6-95be304ea9cc",
      "subscription_id": "991740dd-d1d3-4f80-81ad-7062388aaedc"
    }
  }
}

Non-identified Bank Transaction

When an unregistered customer makes a bank transfer to the bank account we opened for you, we will send a notification with the customer's information. You must register this person or company to access the funds from that transaction. If you do not complete the registration, the payment will be refunded within two business days.

{
  "notification": {
    "type": "non_identified_bank_transaction",
    "secret": "your_webhook_secret",
    "bank_transaction": {
      "id": "uuid-of-the-transaction",
      "value": "5000.0",
      "currency": "BRL",
      "movement_date": "2024-01-05",
      "bank_account_id": "uuid-of-the-bank-account",
      "paid_at": "2024-01-05T06:38:56.367425",
      "spei_concepto_de_pago": "only for Mexican transactions, when informed by payer",
      "subject": {
        "document_number": "93111817067",
        "document_type": "cpf",
        "name": "António Elias",
        "bank_account": {
          "bank": "033",
          "branch_number": "0001",
          "account_number": "000001",
          "account_type": "conta-corrente"
        }
      }
    }
  }
}

Parameters

Parameter	Description	Type
`type`	Always `non_identified_bank_transaction`	string
`secret`	The secret you received when enabling webhooks	string
`bank_transaction.id`	UUID of the non-identified transaction	string
`bank_transaction.value`	Transaction value	string
`bank_transaction.currency`	Transaction currency (BRL, MXN, etc.)	string
`bank_transaction.movement_date`	Date of the bank movement	string
`bank_transaction.bank_account_id`	UUID of the receiving bank account	string
`bank_transaction.paid_at`	Timestamp when the payment was received	string
`bank_transaction.spei_concepto_de_pago`	Payment concept (only for MXN transactions)	string
`bank_transaction.subject`	Information about the payer	object

Once you register this individual or company, we will send you a notification with type: identified and the transaction id. The funds will then be made available in your account.

Subject approved

This webhook notifies when a person or company registration has been approved:

{
  "notification": {
    "type": "subject_approved",
    "subject_id": "UUID",
    "secret": "the value you received"
  }
}

Subject reproved

{
  "notification": {
    "type": "subject_reproved",
    "subject_id": "someid",
    "reason": "Some reason for not being approved",
    "items": ["proof_of_address_missing"],
    "secret": "the value you received"
  }
}

This following webhook notifies that a person or company registration has been rejected, as well as the reason for the reproval. This webhook is sent whenever the transaction limit for that person/company is reached, so its status automatically goes to reproved. The API also sends it if the backoffice rejects one or more of the provided documents.

info

Other events that may trigger this webhook:

The address proof document is not valid.

{
  "notification": {
    "type": "subject_reproved",
    "subject_id": "UUID",
    "items": ["proof_of_address_rejected"],
    "secret": "some-secret"
  }
}

The provided tax declaration is too old.

{
  "notification": {
    "type": "subject_reproved",
    "subject_id": "UUID",
    "items": ["old_tax_declaration"],
    "secret": "some-secret"
  }
}

Customer´s transactioned amount and provided tax declaration values mismatch.

{
  "notification": {
    "type": "subject_reproved",
    "subject_id": "UUID",
    "items": ["tax_declaration_insufficient"],
    "secret": "some-secret"
  }
}

Webhooks for refunded payments

{
  "notification": {
    "type": "payment_refunded",
    "transaction_id": "UUID",
    "secret": "the value you received"
  }
}

If you want to enable the feature of not accepting payments from third parties you will recieve this webhook to let you know that a payment was refunded for this reason. If a dynamic Pix QR code was paid from an account whose ownership is different than of the specified subject_id in the transaction, we will automatically refund the payer and send you this following webhook:

Webhooks for document requests

{
  "notification": {
    "type": "document_required",
    "subject_id": "UUID",
    "required_documents": ["revenue_tax_declaration", "proof_of_address"],
    "secret": "some-secret"
  }
}

For requesting additional documents without changing the customer approval status, the API sends a document_required webhook like:

Webhooks for expired payments

{
  "notification": {
    "type": "payment_expired",
    "transaction_id": "UUID",
    "secret": "some-secret"
  }
}

The payment_expired webhook is sent when:

A Dynamic PIX QR code payment is not paid by the customer within the specified date, or
A Dynamic CLABE transaction is not paid within the expiration period

Enable and disable webhooks​

HTTP Request​

Body Parameters​

Disable Webhooks​

HTTP Request​

Listing sent notifications​

HTTP Request​

Query Parameters​

Marking notifications as received​

HTTP Request​

Path Parameters​

Webhooks for transactions​

Identified transaction​

Exchange created for transaction​

Wire created​

Approved card transaction​

Parameters​

Reproved card transaction​

Parameters​

Request for wire correction​

Error Codes​

Sending the correct bank account details for wire​

HTTP Request​

Account Type Values​

Webhooks for subscriptions​

Subscription activated​

Subscription canceled​

Subscription is complete​

Invoice paid​

Non-identified Bank Transaction​

Parameters​

Webhooks related to customers​

Subject approved​

Subject reproved​

Webhooks for refunded payments​

Webhooks for document requests​

Webhooks for expired payments​

Enable and disable webhooks

HTTP Request

Body Parameters

Disable Webhooks

HTTP Request

Listing sent notifications

HTTP Request

Query Parameters

Marking notifications as received

HTTP Request

Path Parameters

Webhooks for transactions

Identified transaction

Exchange created for transaction

Wire created

Approved card transaction

Parameters

Reproved card transaction

Parameters

Request for wire correction

Error Codes

Sending the correct bank account details for wire

HTTP Request

Account Type Values

Webhooks for subscriptions

Subscription activated

Subscription canceled

Subscription is complete

Invoice paid

Non-identified Bank Transaction

Parameters

Webhooks related to customers

Subject approved

Subject reproved

Webhooks for refunded payments

Webhooks for document requests

Webhooks for expired payments