curl --request POST \
--url https://api.example.com/v1/events \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"event_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"data": {
"loan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"partner_account_id": "<string>",
"instruction_version": 2,
"deposit_id": "<string>",
"ledger_operation_id": "<string>",
"deposit_amount_cents": 123,
"deducted_cents": 2,
"settled_at": "2023-11-07T05:31:56Z",
"from_outside_institution": true,
"into_own_account": true,
"payer_name": "<string>",
"beneficiary_name": "<string>"
}
}
'import requests
url = "https://api.example.com/v1/events"
payload = {
"event_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"data": {
"loan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"partner_account_id": "<string>",
"instruction_version": 2,
"deposit_id": "<string>",
"ledger_operation_id": "<string>",
"deposit_amount_cents": 123,
"deducted_cents": 2,
"settled_at": "2023-11-07T05:31:56Z",
"from_outside_institution": True,
"into_own_account": True,
"payer_name": "<string>",
"beneficiary_name": "<string>"
}
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
event_id: '<string>',
created_at: '2023-11-07T05:31:56Z',
data: {
loan_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
partner_account_id: '<string>',
instruction_version: 2,
deposit_id: '<string>',
ledger_operation_id: '<string>',
deposit_amount_cents: 123,
deducted_cents: 2,
settled_at: '2023-11-07T05:31:56Z',
from_outside_institution: true,
into_own_account: true,
payer_name: '<string>',
beneficiary_name: '<string>'
}
})
};
fetch('https://api.example.com/v1/events', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v1/events",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'event_id' => '<string>',
'created_at' => '2023-11-07T05:31:56Z',
'data' => [
'loan_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'partner_account_id' => '<string>',
'instruction_version' => 2,
'deposit_id' => '<string>',
'ledger_operation_id' => '<string>',
'deposit_amount_cents' => 123,
'deducted_cents' => 2,
'settled_at' => '2023-11-07T05:31:56Z',
'from_outside_institution' => true,
'into_own_account' => true,
'payer_name' => '<string>',
'beneficiary_name' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v1/events"
payload := strings.NewReader("{\n \"event_id\": \"<string>\",\n \"created_at\": \"2023-11-07T05:31:56Z\",\n \"data\": {\n \"loan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"partner_account_id\": \"<string>\",\n \"instruction_version\": 2,\n \"deposit_id\": \"<string>\",\n \"ledger_operation_id\": \"<string>\",\n \"deposit_amount_cents\": 123,\n \"deducted_cents\": 2,\n \"settled_at\": \"2023-11-07T05:31:56Z\",\n \"from_outside_institution\": true,\n \"into_own_account\": true,\n \"payer_name\": \"<string>\",\n \"beneficiary_name\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/v1/events")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"event_id\": \"<string>\",\n \"created_at\": \"2023-11-07T05:31:56Z\",\n \"data\": {\n \"loan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"partner_account_id\": \"<string>\",\n \"instruction_version\": 2,\n \"deposit_id\": \"<string>\",\n \"ledger_operation_id\": \"<string>\",\n \"deposit_amount_cents\": 123,\n \"deducted_cents\": 2,\n \"settled_at\": \"2023-11-07T05:31:56Z\",\n \"from_outside_institution\": true,\n \"into_own_account\": true,\n \"payer_name\": \"<string>\",\n \"beneficiary_name\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/events")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"event_id\": \"<string>\",\n \"created_at\": \"2023-11-07T05:31:56Z\",\n \"data\": {\n \"loan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"partner_account_id\": \"<string>\",\n \"instruction_version\": 2,\n \"deposit_id\": \"<string>\",\n \"ledger_operation_id\": \"<string>\",\n \"deposit_amount_cents\": 123,\n \"deducted_cents\": 2,\n \"settled_at\": \"2023-11-07T05:31:56Z\",\n \"from_outside_institution\": true,\n \"into_own_account\": true,\n \"payer_name\": \"<string>\",\n \"beneficiary_name\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"event_id": "<string>",
"loan": {
"loan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "<string>",
"currency": "USD",
"principal_cents": 123,
"interest_cents": 123,
"hold_cents": 123,
"outstanding_cents": 123,
"installments": [
{
"seq": 123,
"amount_due_cents": 123,
"principal_due_cents": 123,
"interest_due_cents": 123,
"amount_paid_cents": 123,
"due_date": "2023-12-25",
"provisional_due_date": "2023-12-25",
"paid_at": "2023-11-07T05:31:56Z",
"status": "<string>"
}
],
"instructions": [
{
"instruction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "place_hold",
"amount_cents": 123,
"currency": "USD",
"issued_at": "2023-11-07T05:31:56Z"
}
],
"deduction": {
"instruction_version": 2,
"status": "active",
"installment_seq": 123,
"amount_cents": 123,
"currency": "USD",
"deposit_filter": "inbound_bank_transfer_from_outside",
"max_deposit_pct": 100
}
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
"<unknown>"
]
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
"<unknown>"
]
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
"<unknown>"
]
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
"<unknown>"
]
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
"<unknown>"
]
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
"<unknown>"
]
},
"request_id": "<string>"
}Report a settled deposit, a Tradevu repayment, or a confirmed or failed instruction
The body is the webhook envelope {event_id, type, created_at, data}. type is
deposit.settled, tradevu.repayment, hold.placed, payout.confirmed, hold.released,
refund.paid or instruction.failed; any other type is a 400 with details
[{"field": "type"}]. Every 202 carries the loan’s current view, the same as
GET /v1/loans/{loan_id}. Use the event_id as the Idempotency-Key. Repeating an event_id, or
a repayment_id already posted, answers 202 and posts nothing new. Every object rejects
unknown fields. A 400 names each failing field as {"field": "data.principal_cents"}. A data
block that does not parse (a missing, unknown or mistyped field) is a 400 with the message
invalid event and no details.
A repayment_id already posted for a different loan is a 400 with details
[{"field": "data.repayment_id"}].
A deposit.settled posts one ledger journal and sends the next deduction instruction. It is
accepted while the loan is current, overdue, delinquent, default, restructured or repaid (a
deposit on a repaid loan is all overpayment, and a refund is queued); any other status is
409 INVALID_STATE. An instruction_version above the loan’s current version, or a
ledger_operation_id already posted for a different loan, is a 400 with details
[{"field": "data.instruction_version"}] or [{"field": "data.ledger_operation_id"}].
payer_name and beneficiary_name are used only to classify the deposit and are not stored.
Final answers are 400 VALIDATION_FAILED, 404, 409 INVALID_STATE, 409 IDEMPOTENCY_KEY_REUSED,
413 PAYLOAD_TOO_LARGE and 422 REPAYMENT_EXCEEDS_LINE: a repeat with the same Idempotency-Key
replays the stored response, so send a corrected event under a new event_id. Retry a 5xx,
409 REQUEST_IN_PROGRESS and 429 with the same Idempotency-Key and body. Retry a 401 after
refreshing the token. A 400 IDEMPOTENCY_KEY_REQUIRED or IDEMPOTENCY_KEY_INVALID is not stored:
fix the header and send again.
A tradevu.repayment is refused with 409 INVALID_STATE only while the loan is
pending_disbursement or cancelled, and with 422 REPAYMENT_EXCEEDS_LINE when it is above the
loan’s outstanding Tradevu line.
hold.placed, payout.confirmed, hold.released and refund.paid confirm a
place_hold, pay_out, release_hold or refund instruction; instruction.failed
reports that any of them could not be done. An unknown instruction_id, or another partner’s,
is a 404. Field errors are checked next, before the instruction’s state, in this order, each a
400 naming its field: instruction_id must name an instruction of this loan whose kind matches
the type (data.instruction_id), amount_cents must equal the instruction’s amount,
reference is 1 to 128 characters, done_at / failed_at is no more than 5 minutes ahead of
our clock, and reason is one of insufficient_balance, account_blocked, other. Then
the state: resending an identical confirmation (same reference and amount_cents) or an
identical failure (same reason) answers 202 and changes nothing, under any event_id; any
other event on an instruction already confirmed or failed is 409 INVALID_STATE. There is no
deadline: a confirmation or failure sent hours later still applies. A place_hold is issued
once the bureau check passes. release_hold and refund are issued within seconds after the
event that causes them, so they are not in that event’s answer. A failed pay_out is replaced
by a new pay_out instruction, up to 3 in all; after the third failure the loan is cancelled
and a release_hold is issued. A failed release_hold or refund is not issued again.
curl --request POST \
--url https://api.example.com/v1/events \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"event_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"data": {
"loan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"partner_account_id": "<string>",
"instruction_version": 2,
"deposit_id": "<string>",
"ledger_operation_id": "<string>",
"deposit_amount_cents": 123,
"deducted_cents": 2,
"settled_at": "2023-11-07T05:31:56Z",
"from_outside_institution": true,
"into_own_account": true,
"payer_name": "<string>",
"beneficiary_name": "<string>"
}
}
'import requests
url = "https://api.example.com/v1/events"
payload = {
"event_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"data": {
"loan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"partner_account_id": "<string>",
"instruction_version": 2,
"deposit_id": "<string>",
"ledger_operation_id": "<string>",
"deposit_amount_cents": 123,
"deducted_cents": 2,
"settled_at": "2023-11-07T05:31:56Z",
"from_outside_institution": True,
"into_own_account": True,
"payer_name": "<string>",
"beneficiary_name": "<string>"
}
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
event_id: '<string>',
created_at: '2023-11-07T05:31:56Z',
data: {
loan_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
partner_account_id: '<string>',
instruction_version: 2,
deposit_id: '<string>',
ledger_operation_id: '<string>',
deposit_amount_cents: 123,
deducted_cents: 2,
settled_at: '2023-11-07T05:31:56Z',
from_outside_institution: true,
into_own_account: true,
payer_name: '<string>',
beneficiary_name: '<string>'
}
})
};
fetch('https://api.example.com/v1/events', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v1/events",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'event_id' => '<string>',
'created_at' => '2023-11-07T05:31:56Z',
'data' => [
'loan_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'partner_account_id' => '<string>',
'instruction_version' => 2,
'deposit_id' => '<string>',
'ledger_operation_id' => '<string>',
'deposit_amount_cents' => 123,
'deducted_cents' => 2,
'settled_at' => '2023-11-07T05:31:56Z',
'from_outside_institution' => true,
'into_own_account' => true,
'payer_name' => '<string>',
'beneficiary_name' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v1/events"
payload := strings.NewReader("{\n \"event_id\": \"<string>\",\n \"created_at\": \"2023-11-07T05:31:56Z\",\n \"data\": {\n \"loan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"partner_account_id\": \"<string>\",\n \"instruction_version\": 2,\n \"deposit_id\": \"<string>\",\n \"ledger_operation_id\": \"<string>\",\n \"deposit_amount_cents\": 123,\n \"deducted_cents\": 2,\n \"settled_at\": \"2023-11-07T05:31:56Z\",\n \"from_outside_institution\": true,\n \"into_own_account\": true,\n \"payer_name\": \"<string>\",\n \"beneficiary_name\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/v1/events")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"event_id\": \"<string>\",\n \"created_at\": \"2023-11-07T05:31:56Z\",\n \"data\": {\n \"loan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"partner_account_id\": \"<string>\",\n \"instruction_version\": 2,\n \"deposit_id\": \"<string>\",\n \"ledger_operation_id\": \"<string>\",\n \"deposit_amount_cents\": 123,\n \"deducted_cents\": 2,\n \"settled_at\": \"2023-11-07T05:31:56Z\",\n \"from_outside_institution\": true,\n \"into_own_account\": true,\n \"payer_name\": \"<string>\",\n \"beneficiary_name\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/events")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"event_id\": \"<string>\",\n \"created_at\": \"2023-11-07T05:31:56Z\",\n \"data\": {\n \"loan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"partner_account_id\": \"<string>\",\n \"instruction_version\": 2,\n \"deposit_id\": \"<string>\",\n \"ledger_operation_id\": \"<string>\",\n \"deposit_amount_cents\": 123,\n \"deducted_cents\": 2,\n \"settled_at\": \"2023-11-07T05:31:56Z\",\n \"from_outside_institution\": true,\n \"into_own_account\": true,\n \"payer_name\": \"<string>\",\n \"beneficiary_name\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"event_id": "<string>",
"loan": {
"loan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "<string>",
"currency": "USD",
"principal_cents": 123,
"interest_cents": 123,
"hold_cents": 123,
"outstanding_cents": 123,
"installments": [
{
"seq": 123,
"amount_due_cents": 123,
"principal_due_cents": 123,
"interest_due_cents": 123,
"amount_paid_cents": 123,
"due_date": "2023-12-25",
"provisional_due_date": "2023-12-25",
"paid_at": "2023-11-07T05:31:56Z",
"status": "<string>"
}
],
"instructions": [
{
"instruction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "place_hold",
"amount_cents": 123,
"currency": "USD",
"issued_at": "2023-11-07T05:31:56Z"
}
],
"deduction": {
"instruction_version": 2,
"status": "active",
"installment_seq": 123,
"amount_cents": 123,
"currency": "USD",
"deposit_filter": "inbound_bank_transfer_from_outside",
"max_deposit_pct": 100
}
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
"<unknown>"
]
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
"<unknown>"
]
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
"<unknown>"
]
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
"<unknown>"
]
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
"<unknown>"
]
},
"request_id": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": [
"<unknown>"
]
},
"request_id": "<string>"
}