Search
Support
Menu
Edit Template

Get started

Products

Integration

In-depth knowledge

Testing and Go-live

Integrate

Integration of Callbacks

 

This guide explains all aspects about handling notification callbacks for sessions and transactions for all Brite products.

 

The integration steps are:

  1. Subscribe to the notifications

  2. Receive a notification to a callbacks[].url

  3. Confirm the notification with HTTP 200 OK

  4. Request session or transaction details

 

1. Subscribe to the notifications

For each session and transaction you can define the states for which you want to receive notifications. This allows you to react on them and help you process payments in your own system based on them.

 

Example of a request to subscribe to transaction states 4, 5 and 7 and session state 12

				
					...
    "callbacks": [
      {
        "url": "https://merchant.com/callback/?order_id=ORD-12345-ABC",
        "transaction_state": 4 // STATE_COMPLETED for the transaction
      },
      {
        "url": "https://merchant.com/callback/?order_id=ORD-12345-ABC",
        "transaction_state": 5 // STATE_CREDIT
      },
      {
        "url": "https://merchant.com/callback/?order_id=ORD-12345-ABC",
        "transaction_state": 7 // STATE_DEBIT
      },
      {
        "url": "https://merchant.com/callback/?order_id=ORD-12345-ABC",
        "session_state": 12 // STATE_COMPLETED for the session
      },
    ],
  ...

Add this to your request to create a payment, payout or refund.

For a detailed overview of all transaction states and for all session states.

 

2. Receive a notification to a callbacks[].url

Brite sends the notification as a POST request with user-agent: Brite Callback to the url assigned to the respective state. This means that if a session moves to state 12 or a transaction to state 5 you will get a notification containing your merchant_id the session_id or transaction_id and the state as session_state or transaction_state. Note that the *_state parameters are numerical.

This means you can handle all callbacks with one logic on your end. The notifications allow you to identify the session, transaction and merchant by their ids. We recommend adding your own parameters to the callback urls, for example ?order_id=ORD-12345-ABC. This allows you to identify the associated orders in your system easier.

 

Sessions: example of a session_state notification

This notification is posted to the callbacks[].url you provided in the initial request.

				
					POST <callbacks[].url> // EXAMPLE: POST /callback/?order_id=ORD-12345-ABC
user-agent: Brite Callback
content-type: application/json
accept-encoding: gzip, deflate

{
    "merchant_id": "ag9ofmFib25lYS0xNzYyMTNyFQsSCE1lcmNoYW50GICAgID4woQKDA",
    "session_id": "ag9ofmFib25lYS0xNzYyMTNyFAsSB1Nlc3Npb24YgICAjeqInQgM",
    "session_state": 12 // STATE_COMPLETED
}

You should store the session_id alongside the order in your system.

 

Transaction: example of a transaction_state notification

This notification is posted to the callbacks[].url you provided in the initial request.

				
					POST <callbacks[].url> // EXAMPLE: POST /callback/?order_id=ORD-12345-ABC
user-agent: Brite Callback
content-type: application/json
accept-encoding: gzip, deflate

{
    "merchant_id": "ag9ofmFib25lYS0xNzYyMTNyFQsSCE1lcmNoYW50GICAgID4woQKDA",
    "transaction_id": "ag9ofmFib25lYS0xNzYyMTNyFQsSC1RyYW5zYWN0aW9uGJX6itYBDA",
    "transaction_state": 6 // STATE_SETTLED
}

You should store the transaction_id alongside the order in your system.

 

3. Confirm the notification with HTTP 200 OK

Once you retrieve the notification and stored the respective data points, you should respond with a HTTP 200 OK. Otherwise Brite will send further notifications until you confirmed them.

Attempt Notification time
1st (first) 0 minutes (that is immediately once the state changed)
2nd 10 minutes
3rd 30 minutes
4th (last) 60 minutes

 

4. Request session or transaction details

For security reasons, the notification contains only limited data on the session or transaction. This means in order to process the session or transaction update, you have to fetch the details after the notification. You get all data points with a POST request on the session or transaction.

Get session details with POST /api/session.get and add the id in the request body.

Get transaction details with POST /api/transaction.get and add the id in the request body.

 

Example request for fetching transaction details

				
					POST /api/transaction.get HTTP/1.1
Content-Type: application/json
{
    "id": "ag9ofmFib25lYS0xNzYyMTNyFQsSC1RyYW5zYWN0aW9uGOOznssBDA"
}

 

Response with the transaction details

				
					{
    // Identifiers
    "id": "ag9ofmFib25lYS0xNzYyMTNyFQsSC1RyYW5zYWN0aW9uGOOznssBDA",
    "deposit_transaction_id": "DEP-456",
    "session_id": "ag9ofmFib25lYS0xNzYyMTNyFAsSB1Nlc3Npb24YgICA1Y6EigsM",
    "related_transaction_id": "TRX-REF-002",
    "customer_id": "ag9ofmFib25lYS0xNzYyMTNyFQsSCEN1c3RvbWVyGICAgIbWsK0IDA",
    "merchant_reference": "ORD-ABC-123",
    "merchant_id": "ag9ofmFib25lYS0xNzYyMTNyFQsSCE1lcmNoYW50GICAgID4woQKDA",
    "fee_id": "FEE-999",

    // Status and State
    "state": "STATE_FAILED",
    "type": 1,
    "approved": 1735725600,
    "created": 1735725540,
    "completed": 1735725900,
    "credited": 1735726200,
    "debited": 1735725780,
    "settled": 1735729200,
    "error_code": "psu_abandoned_session",
    "message": "RF8QHMTG6M",
    "manual_approval_reason": "Awaiting KYC verification",

    // Amount and Currency
    "amount": 100.00,
    "currency_id": "SEK",
    "fee_amount": 100,

    // Bank Account Information
    "from_bank_account_id": "BANKACC-XYZ",
    "from_bank_account": {
        "bank_name": "Example Bank",
        "bban": "12345678901",
        "country_id": "SE",
        "iban": "SE1234567890123456789012"
    },
    "to_bank_account_id": "DISREGARD-ACCT",
    "to_bank_account": {
        "bank_name": "DISREGARD-BANK",
        "bban": "DISREGARD-BBAN",
        "country_id": "XX",
        "iban": "DISREGARD-IBAN"
    },

    // Other
    "country_id": "SE", // Placed here as it's used in multiple contexts
    "eta": 1735819200,
    "statement_reference": "DISREGARD-XYZ"
}

Despite that there are plenty of transaction details, we recommend processing only a few:

 

from_bank_account_id

This id represents the originating bank account of the customer. If you want to use Brite Instant Payouts, you will be asked to provide this id in the payout request as bank_account_id. So we recommend storing it alongside the customer profile in your system.

 

error_code

This can help you understand what went wrong and why a particular payment failed. See a full list of all error codes.

 

state

The state of the transaction should be stored and updated alongside your order in your system. For a detailed overview of all transaction states and for all session states.

 

customer_id

The customer id identifies this very customer. When you pass that as a parameter to payments, Brite blocks any other customer from completing the payment.

 

message

The message shows on the customer's bank statement as part of the payment's details in their online banking. It is typically referred to as bank statement reference or just reference in the context of the bank transfer.

 

type

There are different types of transactions. If you choose to handle callbacks for payments, payouts or refunds on the same url, the type allows you to distinguish between them.

Typically, the relevant types for you to handle are

  • type: 0 payment (also called deposit),

  • type: 1 payout (also called withdrawal),

  • type: 15 refund and

  • type : 13 returned funds.

 

IP Whitelist

 Please note that in order to use this service you must whitelist the following IP addresses:
Sandbox
Production
35.228.90.52
35.228.90.52
34.107.68.175
34.107.68.175
34.159.115.166
34.141.92.135
34.141.92.135
34.141.49.184
34.141.49.184
35.246.194.85
35.246.194.85
Brite AB

Linnégatan 5
114 47 Stockholm
Sweden

Technical Resources
Marketing
Checkout Guidelines
Company
Contact

Brite AB (corporate identity number: 559116-1632) is a licensed Payment Institution under the supervision of the Swedish Financial Supervisory Authority (Finansinspektionen). Brite AB provides payment services under the Swedish Payment Services Act (2010:751) as well as the EU Directive 2015/2366 about payment services in the internal market (PSD2) and has, upon notification, the authority to provide payment services across EU/EES.

© 2024 Brite AB