To payout money to or collect money from your customers, you need to generate Orders and Instructions. An Instruction tells Imburse when and how much to payout to or collect from your customer.
For more information on Order Management, see Order Management in Getting Started.
In addition to familiarity with the Core Concepts, you’ll need the following:
Access Token
derived from a Tenant API Key
The steps involved in managing orders are:
Each Order can have multiple Instructions. In this tutorial we will only create one instruction.
Repeat Step 2 for each instruction you need to add to an order. Just change the Instruction Ref to make sure they are unique per instruction in an order.
You can optionally create the instructions during the creation of the order too. For our example we’ll use separate requests.
Using the Access Token
we can create an Order.
Replace the {access-token}
placeholder value with the Access Token
value.
Replace the orderRef
property value (REF1 in the example below) with the a suitable value to identity this Order. Usually this would be the order reference you have from your internal systems.
The metadata
property can be filled with arbitrary key-value-pairs that help contextualize the order for you. We will pass the metadata back to you in the webhook notifications for you internal systems to disseminate.
curl --location --request POST "https://sandbox-api.imbursepayments.com/v1/order-management" \
--header "Authorization: Bearer {access-token}" \
--header "Content-Type: application/json" \
--data "{
\"orderRef\": \"REF1\",
\"instructions\": [],
\"metadata\": {
\"someInternalRef2\": \"another-internal-ref\"
},
\"customerDefaults\": {
}
}"
The response will be 201 - Created
Using the Access Token
we can create an Instruction.
Replace the {access-token}
placeholder value with the Access Token
value.
Replace the {orderRef}
placeholder value with the same Order Ref value you gave in Step 1.
Replace the instructionRef
, amount
, and {settled_by_date}
properties with more relevant data. Date format is yyy-mm-dd
.
curl --location --request POST "https://sandbox-api.imbursepayments.com/v1/order-management/{orderRef}/instruction" \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--data "{
\"instructionRef\": \"I01\",
\"customerRef\": \"C01\",
\"direction\": \"CREDIT\",
\"financialInstrumentId\": \"\",
\"amount\": \"210.00\",
\"currency\": \"EUR\",
\"country\": \"DE\",
\"settledByDate\": \"{settled_by_date}\"
\"scheme\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",
\"metadata\": []
}"
The response will be 201 - Created
{
"direction": "",
"status": "",
"customerRef": "C01",
"financialInstrument": {
"financialInstrumentId": "",
"source": "NONE",
"canUpdate": true
},
"amount": 210,
"currency": "EUR",
"country": "DE",
"settledByDate": "2020-12-31T00:00:00.000Z",
"Scheme": {
"schemeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"source": "",
"canUpdate": true
},
"metaData": []
}