Manual Bank Transfer (MBT) enables your customers to transfer money directly from their bank account. Present this as a payment method in your checkout to your customers and receive real time updates from Ivy when the funds land in your Collection Account.
High Level Flow
Create an Order
Create an Order with the /order/create endpoint. You will receive the destination in the response.
Display Payment Details
Display the destination to your customer as the payment instructions.
Track the Status
Track the status of the order from processing until it is on status paid. See our Status Flow documentation for more information.
Step by Step Guide
Step 1: Create an Order
To create an order, you can either use our Node.js SDK or you can directly call the endpoint via HTTP.
curl -X POST https://api.getivy.de/api/service/order/create \
-H "X-Ivy-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": 1.23,
"currency": "EUR",
"referenceId": "your-internal-reference",
"customer": {
"email": "[email protected]"
}
}'
import express from 'express';
import Ivy from '@getivy/node-sdk';
import { OrderCreateParams } from '@getivy/node-sdk/resources/order';
const router = express.Router();
const ivy = new Ivy('YOUR_API_KEY');
router.post('/your-server-endpoint', async (req, res) => {
try {
const params: OrderCreateParams = {
amount: req.body.amount, // Required, in decimals e.g. 1.23 for 1.23 EUR
currency: req.body.currency || 'EUR', // Required, currency of the amount
referenceId: req.body.referenceId, // Required, your internal reference for this order
customer: {
email: req.body.customer?.email // Optional, email of the customer
},
expiresAt: req.body.expiresAt, // Optional, defaults to 6 days from now
};
const order = await ivy.order.create(params);
res.json(order.destination); // The destination to which the customer should transfer the money
} catch (error) {
console.error("Failed to create order", error);
res.status(400).json({ error: 'Failed to create order' });
}
});
export default router;
<?php
$apiKey = 'YOUR_API_KEY';
$url = 'https://api.getivy.de/api/service/order/create';
$data = [
'amount' => 1.23,
'currency' => 'EUR',
'referenceId' => 'your-internal-reference',
'customer' => [
'email' => '[email protected]'
]
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'X-Ivy-Api-Key: ' . $apiKey,
'Content-Type: application/json'
]);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
Step 2: Display Bank Details
After creating the order, you’ll receive bank transfer details in the response. Use the destination field to display the payment instructions to your customer.
The destination to which the customer should transfer the money.
destination.bankAccount.iban.iban
The IBAN of the account to which the customer should transfer the money.
destination.bankAccount.iban.accountHolderName
The name of the account holder to which the customer should transfer the money.
destination.bankAccount.iban.bic
The BIC of the account to which the customer should transfer the money.
destination.bankStatementReference
The reference to be displayed on the customer’s bank statement.
Example Response{
"destination": {
"bankAccount": {
"iban": {
"iban": "DE34817329488882190",
"accountHolderName": "Test Merchant",
"bic": "BCIRLLLL"
}
},
"bankStatementReference": "ir4d23bcd816e89ef"
}
}
destination.bankAccount.sortCode.sortCode
The Sort Code of the account to which the customer should transfer the money.
destination.bankAccount.sortCode.accountNumber
The Account Number of the account to which the customer should transfer the money.
destination.bankAccount.sortCode.accountHolderName
The name of the account holder to which the customer should transfer the money.
destination.bankStatementReference
The reference to be displayed on the customer’s bank statement.
Example{
"destination": {
"bankAccount": {
"sortCode": {
"sortCode": "123456",
"accountNumber": "1234567890",
"accountHolderName": "John Doe"
}
},
"bankStatementReference": "irf1234556679"
}
}
Display these details to your customer as per the UX guidance below, so that they can accurately complete the transfer.
Step 3: Track the Status
Monitor the order status to know when the payment is complete. For detailed information about order statuses and their meaning, see our Status Flow documentation.
- When the order is created, the status will be
processing.
- When the payment is received and reconciled into your Collection Account, the order will be updated to
paid.
If the payment does not arrive or cannot be reconciled (i.e. the customer never sent the funds or payment information was incorrect) then the status will remain as processing for 6 days at which point it will move to failed.
If a payment is received with an incorrect amount or payment reference then it will be automatically rejected and returned to the customer. It is critical that all payment information is included in the Manual Bank Transfer so that the payment can be reconciled.
Need Help?