Callbacks

Callback URLs

Product

Endpoint

Auth

GET /v1/callback?record=*{RECORD ID HERE}*&method=AUTH

Transactions

GET /v1/callback?record=*{RECORD ID HERE}*&method=TRANSACTIONS

Identity

GET /v1/callback?record=*{RECORD ID HERE}*&method=IDENTITY

Income

GET /v1/callback?record=*{RECORD ID HERE}*&method=INCOME

Balance

GET /v1/callback?record=*{RECORD ID HERE}*&method=BALANCE

Transaction Callback

You can receive notifications via a callback whenever there are new transactions associated with a Record, including when Okra initial and historical transaction pull are completed. All callbacks related to transactions have a callback_type of TRANSACTIONS.

Code

Details

INITIAL_TRANSACTIONS

Fired when a Record's initial transaction pull is completed. Note: The default pull is 30 days

FULL_TRANSACTIONS

Fired when a Record's historical transaction pull is completed. Okra fetches as much data as is available from the bank.

PERIODIC_TRANSACTIONS

Fired when new transaction data is available as Okra performs its regular updates of the Record.

TRANSACTIONS_DELETED

Fired when posted transaction(s) for a Record are deleted. The deleted transaction IDs are included in the callback payload.

The callback must be in the standard format of http(s)://(www.)domain.com/. The response will contain a corresponding success message and code along with the same record ID that was returned in the initial call (examples below). Once the transaction processing has finished, you can use the Record's token to collect the full account and transaction information for that user.

All transactions callbacks will have a callback_type equal to TRANSACTIONS. Each callback payload will also include a unique callback_code and the record_id for which the callback is being fired.

Initial transaction callback

{
"callback_type": "TRANSACTIONS",
"callback_code": "INITIAL_TRANSACTIONS",
"record": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
"error": null,
"new_transactions": 19
}

Historical transaction callback

{
"callback_type": "TRANSACTIONS",
"callback_code": "FULL_TRANSACTIONS",
"record": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
"error": null,
"new_transactions": 231
}

Default transaction callback

{
"callback_type": "TRANSACTIONS",
"callback_code": "PERIODIC_TRANSACTIONS",
"record": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
"error": null,
"new_transactions": 3
}

Removed transaction callback

{
"callback_type": "TRANSACTIONS",
"callback_code": "TRANSACTIONS_DELETED",
"record": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
"removed_transactions": [
"yBVBEwrPyJs8GvR77N7QTxnGg6wG74H7dEDN6",
"kgygNvAVPzSX9KkddNdWHaVGRVex1MHm3k9no"
],
"error": null
}
`

Record Callback

Callbacks are also used to communicate changes to a Record such as an updated callback, or errors encountered with a Record. The error typically requires user action to resolve, such as when a user changes their password. For a complete list of possible errors, see Errors.

Code

Details

WEBHOOK_UPDATE_ACKNOWLEDGED

Fired when a Record's callback is updated.

ERROR

Fired when an error is encountered with a Record. The error can be resolved by having the user go through Link’s update mode.

The callback must be in the standard format of http(s)://(www.)domain.com/. The response will contain a corresponding success message and code along with the same record_id that was returned in the initial call (examples below). Once the transaction processing has finished, you can use the Record's token to collect the full account and transaction information for that user.

All transactions callbacks will have a callback_type equal to TRANSACTIONS. Each callback payload will also include a unique callback_code and the record_id for which the callback is being fired.

Record's callback updated callback

{
"callback_type": "RECORD",
"callback_code": "WEBHOOK_UPDATE_ACKNOWLEDGED",
"record": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
"error": null,
"new_callback_url": "https://okra.ng/example/callback"
}

Record error callback

{
"callback_type": "RECORD",
"callback_code": "ERROR",
"record": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
"error": {
"display_message": "The provided credentials were not correct. Please try again.",
"error_code": "RECORD_LOGIN_REQUIRED",
"error_message": "the provided credentials were not correct",
"error_type": "RECORD_ERROR",
"status": 400
}
}

Income Callback

If you're using callbacks with the Incomeproduct, you'll receive a callback when Okra calculates the Income data for the Record. Once you receive this callback, you can make an /income/get API request to retrieveIncomedata.

Income ready callback

{
"callback_type": "INCOME",
"callback_code": "PDOCUT_IS_READY",
"record": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
"error": null
}

Identity Callback

If you're using callbacks with the Identity product, you'll receive a callback when Okra calculates the Identity data for the Record. Once you receive this callback, you can make an /identity/get API request to retrieve Identity data.

Identity ready callback

{
"callback_type": "IDENTITY",
"callback_code": "PRODUCT_IS_READY",
"record": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
"error": null
}

Balance Callback

If you're using callbacks with the Balance product, you'll receive a callback when Okra calculates the Balance data for the Record. Once you receive this callback, you can make an /balance/get API request to retrieve Balancedata.

Code

Details

INITIAL_BALANCE

Fired when a record's initial balance pull is completed. Note: The default pull is 30 days

PERIODIC_BALANCE

Fired when new balance data is available as Okra performs its regular updates of the Record.

BALANCE_DELETED

Fired when posted balance(s) for a Record are deleted. The deleted balance IDs are included in the callback payload.

Balance ready callback

{
"callback_type": "BALANCE",
"callback_code": "PRODUCT_IS_READY",
"record": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
"error": null
}