This page describes how to create a payin, which will allow you to send customer and order data to Banked, display the checkout page, and check the status of the payin.
1. Authentication
Follow the instructions on the Authentication page to get your account credentials and generate an OAuth token. You'll need to use your test credentials until your application is ready to deploy.
You will use your API key and secret key with the /token endpoint to generate a scoped OAuth token. To use the example requests on this page, replace YOUR_OAUTH_TOKEN with the one you generate.
2. Create a Payin
A payin is a request to collect funds from a payer. Send a POST request to the /v3/payins endpoint to create one — Banked returns a checkout URL to present to your customer and a payin ID to track the payment lifecycle.
By default you are only permitted to create payins with a creditor account that matches a previously registered bank account (identified by BSB + account number in Australia). In the test environment, a test bank account is created automatically when you sign up. Use the bank_account_id provided to you by the Banked support team.
The following cURL command creates a payin. Remember to replace YOUR_OAUTH_TOKEN with the token you generated in the authentication step and YOUR_BANK_ACCOUNT_ID with your registered bank account ID:
curl --location --request POST 'https://api.banked.com/v3/payins' \
--header 'Authorization: Bearer YOUR_OAUTH_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \
--header 'Signature: YOUR_SIGNATURE' \
--data-raw '{
"amount": 400,
"currency": "AUD",
"checkout_config": {
"redirect_url": "https://example.com/"
},
"payment_identification": {
"end_to_end_identification": "order123"
},
"ultimate_creditor": {
"identity_type": "PARTY_IDENTIFICATION",
"name": "Payments R Us"
},
"remittance_information": {
"unstructured": "Candles order",
"structured": {
"creditor_reference_information": {
"reference": "InternalMerchantID123"
}
}
},
"processing_method": {
"method_type": "ACCOUNT_TO_ACCOUNT",
"creditor_account": {
"account_type": "BANKED_BANK_ACCOUNT_ENTITY",
"bank_account_id": "YOUR_BANK_ACCOUNT_ID"
}
}
}'
The end_to_end_identification flows through the entire payment chain and is what typically appears on the payer's bank statement.
The creditor_reference_information.reference is structured remittance data for your own reconciliation (e.g. an invoice number) and may not be visible to the payer in their banking app.
The /v3/payins endpoint returns a Payin object with the URL required to access the web checkout and complete the payment in the checkout_config.checkout_url field:
{
"id": "1ae1ce03-dfa9-4593-b487-65c656991cb5",
"created_at": "2024-11-01T15:48:26.374Z",
"updated_at": "2024-11-01T15:48:26.374Z",
"amount": 400,
"currency": "AUD",
"status_details": {
"status": "CREATED"
},
"checkout_config": {
"redirect_url": "https://example.com/",
"checkout_url": "https://checkout.banked.com/1ae1ce03-dfa9-4593-b487-65c656991cb5"
},
"creditor_account": {
"account_type": "BANKED_BANK_ACCOUNT_ENTITY",
"bank_account_id": "7bbfe368-98ec-4289-983f-70de6d498959"
},
"ultimate_creditor": {
"identity_type": "PARTY_IDENTIFICATION",
"name": "Payments R Us"
},
"payment_identification": {
"end_to_end_identification": "order123"
},
"remittance_information": {
"unstructured": "Candles order",
"structured": {
"creditor_reference_information": {
"reference": "InternalMerchantID123"
}
}
}
}
Use the checkout_config.checkout_url to redirect your customer to the Banked checkout page.
3. Checkout with the Mock Bank
Use the checkout_config.checkout_url value from the payin response to access the web checkout. You can see details of the payin and progress through the full checkout flow as a real customer would.
The key difference is we provide a 'mock' bank for testing, which doesn't require the need for a real Australian bank account. It also offers the ability to test pending and failed payins without any money moving between providers.
4. View Payin Status
Send a GET request to the /v3/payins/{payin_id} endpoint to retrieve the payin object. The response includes the status in the status_details.status field. See the Payin Status reference page for details about the values in the status_details.status field.
curl --location --request GET 'https://api.banked.com/v3/payins/1ae1ce03-dfa9-4593-b487-65c656991cb5' \ --header 'Authorization: Bearer YOUR_OAUTH_TOKEN' \ --header 'Signature: YOUR_SIGNATURE'
If you have webhooks configured, you will receive a notification when the payin status changes.