Português

Betting platforms

For betting platforms that will use PIX as the payment mehtod the integration will, usually, consist in 3 steps:

Find below a detailed explanation of each step.

1. Inicial setup

The initial setup is described in the general setup section, and no specific configuration is required in this case. The general configuration has two steps:

Obtaining an API Token to communicate with our API
Setting up a processor that will enable operations with the partner banking service

2. Requests to our endpoints

Request a deposit endpoint

The deposits endpoint is the one that will be used to request a QR code for the PIX payment. You can use this endpoint like described on the request details following this link.

Let's take a look on the required fields for the deposits endpoint:

Field name	Data type	Filter type
`amount`	float	Decimal value of the amount being charged (in R$)
`merchant_transaction_id`	string	Transaction id on the side of the merchant
`first_name`	string	First name of the one being charged
`last_name`	string	Last name of the one being charged
`email`	string	Email address for the one being charged
`document_number`	string	Document number for the one being charged. Usually CPF for people and CNPJ for companies.

When it comets to betting platforms, you will probably have most of the required fields comming from the customer account. The only field that you will need to fill is the amount field.

This is the expected workflow for the deposits:

sequenceDiagram
    autonumber
    actor Customer
    Customer ->> Betting platform: Requests a deposit for
    Betting platform ->> Gateway: [POST] /api/pix/charge

    alt Compliance / Validation issue
        rect rgba(0, 0, 255, .1)
            Gateway ->> Betting platform: Return 422 error
            Betting platform ->> Customer: Show error message
        end
    else Success
        Gateway ->> Banking partner: Requests the QR code
        Banking partner ->> Gateway: Returns the QR code
        Gateway ->> Betting platform: Returns the QR code
        Betting platform ->> Customer: Shows the QR code

        Customer -->> Banking partner: Makes the PIX payment
        Banking partner ->> Gateway: Returns the payment confirmation
        Gateway ->> Betting platform: [Webhook] Successfull deposit
        Betting platform ->> Customer: Credits the customer account
    end

On Step 2, When making a request to the [POST] /api/pix/charge endpoint you will receive a 422 error if the customer is not compliant or if the PIX key is not valid. In this case you should show an error message to the customer. This transaction will not be processed and will be marked with a failure status on our side.

If everything is ok, the gateway will request the QR code to the banking partner and return it to the betting platform. The betting platform will show the QR code to the customer (Steps 5 to 8).

On Step 9, the customer will make the PIX payment and the banking partner will return the payment confirmation to the gateway. The gateway will then send a successfull deposit webhook to the betting platform. The betting platform will then credit the customer account with the amount of the deposit.

Important

The user account should be credited only after receiving the successfull deposit webhook. This is the only way to guarantee that the payment was processed and the customer account should be credited.

Request a withdraw endpoint

The withdraws endpoint is the one that will be used to request a withdraw from the betting platform to customer bank account. You can use this endpoint like described on the request details following this link.

Let's take a look on the required fields for the withdraws endpoint:

Field name	Data type	Filter type
`merchant_transaction_id`	string	Transaction id on the side of the merchant
`amount`	float	Decimal value of the amount being charged (in R$)
`pix_key_type`	string	The type of the PIX Key being used, see reference above
`pix_key_value`	string	The value of PIX Key being used
`first_name`	string	Receiver's first name
`last_name`	string	Receiver's last name
`document_number`	string	Receiver's document
`email`	string	Receiver's email

When it comets to betting platforms, you will probably have most of the required fields comming from the customer account. The only field that you will need to fill is the amount field. Other than that, you might want to let your user select the pix key for wich it wants to receive the withdraw. Based on the user preference you should provide the pix_key_type and pix_key_value fields.

This is the expected workflow for the withdraws:

sequenceDiagram
    autonumber
    actor Customer
    Customer ->> Betting platform: Requests a withdraw for
    Betting platform ->> Gateway: [POST] /api/pix/pay

    alt Compliance / Validation / Balance issue
        rect rgba(0, 0, 255, .1)
            Gateway ->> Betting platform: Return 422 error
            Betting platform ->> Customer: Show error message
        end
    else Success
        Gateway ->> Banking partner: Requests the withdraw
        Banking partner ->> Gateway: Withdraw request confirmation
        Gateway ->> Betting platform: Withdraw request confirmation
        Betting platform ->> Customer: Blocks desired withdraw amount

        alt Banking failure
            rect rgba(0, 0, 255, .1)
                Banking partner -->> Gateway: Return the withdraw failure
                Gateway ->> Betting platform: [Webhook] Refund
                Betting platform ->> Customer: Refunds the blocked amount
            end
        else Success
            Banking partner -->> Gateway: Returns the payment confirmation
            Gateway ->> Betting platform: [Webhook] Successfull withdraw
            Betting platform ->> Customer: Withdraws the blocked amount
        end
    end

On Step 2, When making a request to the [POST] /api/pix/pay endpoint you will receive a 422 error if the customer is not compliant or if your account is out of funds. In this case you should show an error message to the customer. This transaction will not be processed and will be marked with a failure status on our side.

If everything is ok, the gateway will request the withdraw to the banking partner and return the withdraw request confirmation to the betting platform. At this point, we recommend the betting platform to block the desired withdraw amount on the customer account (Steps 5 to 8).

On steps 9 to 11, we show the situation where a baking failure occurs. In this case, the banking partner will return the withdraw failure to the gateway. The gateway will then send a refund webhook to the betting platform. The betting platform will then refund the blocked amount to the customer account. This transaction will not be processed and will be marked with a failure status on our side.

On Step 12 to 14, the banking partner will return the payment confirmation to the gateway. The gateway will then send a successfull withdraw webhook to the betting platform. The betting platform will then withdraw the blocked amount from the customer account.

Important

The user account should be both debited (for the successfull case) or refunded (for the withdraw failure) only after receiving the correspondent webhooks. This is the only way to guarantee the payment consistencty betweeen our gateway and your platform.

3. Receiving our webhooks

About our webhooks

Our webhooks are the way we communicate with your platform. They are triggered for every event related to a transaction and can be enabled or disabled on our platform. Each event can point to a different endpoint on your application. The webhook requests are sent as a POST request with a JSON payload.

Our platform considers a webhook susccessfull if it receives a 2xx status code from your platform on the specified endpoint. When a webhook call fails, we will retry it 3 times with a exponential backoff strategy (10, 100 and 1000 seconds of difference between each retry).

The webhooks that will be triggered for the betting platforms are:

Transaction event	Description
`capture`	Successfull deposit: Triggered when a deposit is successfull
`transfer`	Successfull withdraw: Triggered when a withdraw is successfull
`refund`	Failure withdraw: Triggered when a withdraw is not successfull

Receive a successfull deposit webhook (capture)

Every time a a PIX QR Code is generated and paid, the deposit is successfull, our system will deliver a POST webhook in the following format:

Capture webhook example payload

{
  "event": "capture",
  "transaction": {
    "created_at": "2022-02-02T21:34:07+0000",
    "document_number": "****067****",
    "e2e_id": "e00500002120220200000048r0xxv9wwww0l",
    "email": "[email protected]",
    "error": null,
    "events": [
      {
        "amount": "1.00",
        "created_at": "2022-02-02T21:36:03+0000",
        "event_type": "capture",
        "id": "123-456-789",
        "pix_key_type": null,
        "pix_key_value": null,
        "pix_message": null,
        "qrcode": null,
        "qrcode_image": null,
        "success": true,
        "updated_at": "2022-02-02T21:36:03+0000"
      },
      {
        "amount": "1.00",
        "created_at": "2022-02-02T21:34:07+0000",
        "event_type": "auth",
        "id": "123-456-789",
        "pix_key_type": null,
        "pix_key_value": null,
        "pix_message": null,
        "processor_code": "1",
        "processor_message": "pending",
        "processor_transaction_id": "123-456-789",
        "qrcode": "COPYPASTEPIXCODE",
        "qrcode_image": "data:image/png;base64,123123456546789789",
        "success": true,
        "updated_at": "2022-02-02T21:34:10+0000"
      }
    ],
    "first_name": "Foo",
    "id": "123-456-789",
    "last_name": "Bar",
    "merchant_id": "123-456-789",
    "merchant_transaction_id": "0000001",
    "processor_id": "123-456-789",
    "statement": [
        {
        "acc_info": {
          "acc_number": "1122333",
          "acc_type": "checking",
          "bank_agency": "0001",
          "bank_code": "33333",
          "document": "***067***",
          "ispb": "12312311",
          "name": "Foo Bar"
        },
        "amount": "100.00",
        "created_at": "2022-02-02T17:48:27.000000Z",
        "date": "2022-02-02 17:48:26",
        "e2e_id": "e10573521202202121748r0xxv9anj0l"
      }
    ],
    "transaction_type": "pix",
    "updated_at": "2022-02-02T21:36:03+0000",
    "user_id": "123-456-789"
  }
}

For more details you can check the Capture Webhook page.

Receive a successfull withdraw webhook (transfer)

Every time a withdraw is successfull, our system will deliver a POST webhook in the following format:

Pix transfer webhook example payload

{
  "event": "transfer",
  "transaction": {
    "created_at": "2022-02-02T21:34:07+0000",
    "e2e_id": "e0000400202020404040kswkks020202",
    "email": "[email protected]",
    "error": null,
    "events": [
      {
        "amount": "1.00",
        "created_at": "2022-02-02T21:36:03+0000",
        "event_type": "transfer",
        "id": "321-654-987",
        "pix_key_type": null,
        "pix_key_value": null,
        "pix_message": null,
        "qrcode": null,
        "qrcode_image": null,
        "success": true,
        "updated_at": "2022-02-02T21:36:03+0000"
      },
      {
        "amount": "1.00",
        "created_at": "2022-02-02T21:34:07+0000",
        "event_type": "payment",
        "id": "123-456-789",
        "pix_key_type": "email",
        "pix_key_value": "[email protected]",
        "pix_message": "This is NOT a test",
        "processor_code": "1",
        "processor_message": "pending",
        "processor_transaction_id": "123-456-789",
        "qrcode": null,
        "qrcode_image": null,
        "success": true,
        "updated_at": "2022-02-02T21:34:10+0000"
      }
    ],
    "first_name": "Foo",
    "flow_type": "cashout",
    "id": "123-456-789",
    "last_name": "Bar",
    "merchant_id": "123-456-789",
    "merchant_transaction_id": "0000001",
    "processor_id": "123-456-789",
    "statement": [
        {
        "acc_info": {
          "acc_number": "112233",
          "acc_type": "checking",
          "bank_agency": "00001",
          "bank_code": "888",
          "document": "****232****",
          "ispb": "123321",
          "name": "Foo Bar"
        },
        "amount": "450.00",
        "created_at": "2022-02-12T18:00:42.000000Z",
        "date": "2022-02-12 18:00:35",
        "e2e_id": "e0000400202020404040kswkks020202"
      }
    ],
    "status": "success",
    "transaction_type": "pix",
    "updated_at": "2022-02-02T21:36:03+0000",
    "user_id": "123-456-789"
  }
}

For more details you can check the Transfer Webhook page.

Receive a failure withdraw webhook (refund)

Every time a withdraw is not successfull by banking reasons, we have a failed cash out and our system will deliver a POST webhook in the following format:

Pix transfer refunded webhook example payload

{
  "event": "refund",
  "transaction": {
    "created_at": "2022-02-02T21:34:07+0000",
    "document_number": "****435****",
    "e2e_id": null,
    "email": "[email protected]",
    "error": {
      "code": 4,
      "message": "The transfer was rejected by the receiving bank",
      "meta": [],
      "type": "ERROR_BANK_CASH_OUT"
    },
    "events": [
      {
        "amount": "1.00",
        "created_at": "2022-02-02T21:36:03+0000",
        "event_type": "refund",
        "id": "321-654-987",
        "pix_key_type": null,
        "pix_key_value": null,
        "pix_message": null,
        "qrcode": null,
        "qrcode_image": null,
        "success": true,
        "updated_at": "2022-02-02T21:36:03+0000"
      },
      {
        "amount": "1.00",
        "created_at": "2022-02-02T21:34:07+0000",
        "event_type": "payment",
        "id": "123-456-789",
        "pix_key_type": "email",
        "pix_key_value": "[email protected]",
        "pix_message": "This is NOT a test",
        "processor_code": "1",
        "processor_message": "pending",
        "processor_transaction_id": "123-456-789",
        "qrcode": null,
        "qrcode_image": null,
        "success": false,
        "updated_at": "2022-02-02T21:34:10+0000"
      }
    ],
    "first_name": "Foo",
    "flow_type": "cashout",
    "id": "123-456-789",
    "last_name": "Bar",
    "merchant_id": "123-456-789",
    "merchant_transaction_id": "0000001",
    "processor_id": "123-456-789",
    "statement": [
        {
        "acc_info": {
          "acc_number": "string",
          "acc_type": "string",
          "bank_agency": "string",
          "bank_code": "string",
          "document": "string",
          "ispb": "string",
          "name": "string"
        },
        "amount": "450.00",
        "created_at": "2022-02-12T18:00:42.000000Z",
        "date": "2022-02-12 18:00:35",
        "e2e_id": "e0000400202020404040kswkks020202"
      },
      {
        "acc_info": {
          "acc_number": "string",
          "acc_type": "string",
          "bank_agency": "string",
          "bank_code": "string",
          "document": "string",
          "ispb": "string",
          "name": "string"
        },
        "amount": "450.00",
        "created_at": "2022-02-12T18:10:15.000000Z",
        "date": "2022-02-12 18:10:06",
        "e2e_id": "e0000400202020404040kswkks020203"
      }
    ],
    "status": "failed",
    "transaction_type": "pix",
    "updated_at": "2022-02-02T21:36:03+0000",
    "user_id": "123-456-789"
  }
}

For more details you can check the Refund Webhook page.

Betting platforms

1. Inicial required configurations

2. Requests to our endpoints

3. Receiving our webhooks

1. Inicial setup

2. Requests to our endpoints

Request a deposit endpoint

Request a withdraw endpoint

3. Receiving our webhooks

About our webhooks

Receive a successfull deposit webhook (capture)

Receive a successfull withdraw webhook (transfer)

Receive a failure withdraw webhook (refund)