Create Mandate with existing Sender Account
curl --request POST \
--url https://api.prod.finverse.net/mandates/sender_account \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"mandate_details": {
"currency": "<string>",
"description": "<string>",
"end_date": "2023-12-25",
"mandate_bank_reference": "<string>",
"start_date": "2023-12-25"
},
"recipient_account": {
"account_id": "<string>"
},
"sender_account": {
"account_id": "<string>"
},
"metadata": {}
}
'import requests
url = "https://api.prod.finverse.net/mandates/sender_account"
payload = {
"mandate_details": {
"currency": "<string>",
"description": "<string>",
"end_date": "2023-12-25",
"mandate_bank_reference": "<string>",
"start_date": "2023-12-25"
},
"recipient_account": { "account_id": "<string>" },
"sender_account": { "account_id": "<string>" },
"metadata": {}
}
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({
mandate_details: {
currency: '<string>',
description: '<string>',
end_date: '2023-12-25',
mandate_bank_reference: '<string>',
start_date: '2023-12-25'
},
recipient_account: {account_id: '<string>'},
sender_account: {account_id: '<string>'},
metadata: {}
})
};
fetch('https://api.prod.finverse.net/mandates/sender_account', 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.prod.finverse.net/mandates/sender_account",
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([
'mandate_details' => [
'currency' => '<string>',
'description' => '<string>',
'end_date' => '2023-12-25',
'mandate_bank_reference' => '<string>',
'start_date' => '2023-12-25'
],
'recipient_account' => [
'account_id' => '<string>'
],
'sender_account' => [
'account_id' => '<string>'
],
'metadata' => [
]
]),
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.prod.finverse.net/mandates/sender_account"
payload := strings.NewReader("{\n \"mandate_details\": {\n \"currency\": \"<string>\",\n \"description\": \"<string>\",\n \"end_date\": \"2023-12-25\",\n \"mandate_bank_reference\": \"<string>\",\n \"start_date\": \"2023-12-25\"\n },\n \"recipient_account\": {\n \"account_id\": \"<string>\"\n },\n \"sender_account\": {\n \"account_id\": \"<string>\"\n },\n \"metadata\": {}\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.prod.finverse.net/mandates/sender_account")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"mandate_details\": {\n \"currency\": \"<string>\",\n \"description\": \"<string>\",\n \"end_date\": \"2023-12-25\",\n \"mandate_bank_reference\": \"<string>\",\n \"start_date\": \"2023-12-25\"\n },\n \"recipient_account\": {\n \"account_id\": \"<string>\"\n },\n \"sender_account\": {\n \"account_id\": \"<string>\"\n },\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.prod.finverse.net/mandates/sender_account")
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 \"mandate_details\": {\n \"currency\": \"<string>\",\n \"description\": \"<string>\",\n \"end_date\": \"2023-12-25\",\n \"mandate_bank_reference\": \"<string>\",\n \"start_date\": \"2023-12-25\"\n },\n \"recipient_account\": {\n \"account_id\": \"<string>\"\n },\n \"sender_account\": {\n \"account_id\": \"<string>\"\n },\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"fees": [],
"mandate_details": {
"currency": "HKD",
"description": "Test Mandate",
"end_date": "2024-03-01",
"start_date": "2023-10-05",
"transaction_limits": {
"max_period_amount": 10000,
"max_period_count": 10,
"max_transaction_amount": 10000,
"period": "MONTHLY"
}
},
"mandate_id": "01HBZ2K7Y2B7C7TDM7C3BBBZCG",
"metadata": {
"employer_name": "Apple Inc",
"key": "value"
},
"payment_method_id": "01HJ5XHPFR9SDAPZ0Y143R6XCF",
"recipient": {
"name": "John Doe"
},
"recipient_account": {
"account_id": "01GMC9RSPCHAJ9ER9A4JR4AP6X",
"account_type": "SETTLEMENT_ACCOUNT"
},
"sender": {
"external_user_id": "unique_user_id_1695719460",
"name": "John Doe",
"user_details": [
{
"details_type": "HK_ID",
"values": [
"01HB8C32WGQNSP3MMN4P49YT70"
]
}
],
"user_id": "01HB8C32TD4V1RSB1HCZREXVMH",
"user_type": "INDIVIDUAL"
},
"sender_account": {
"account_id": "01HBA46Z9JVR54MWR0YDEZX3XK",
"account_number": {
"number": "01HBA46ZEA306KKDPVE80MYME5",
"type": "LOCAL"
},
"account_number_masked": "132XXXXXXXX4343",
"account_type": "EXTERNAL_ACCOUNT",
"accountholder_name": "01HBA46ZFFKHXQ4F60HRGH9HF4",
"institution_id": "testbank-dbs-hk",
"user_id": "01HB8C32TD4V1RSB1HCZREXVMH"
},
"status": "AUTHORIZATION_REQUIRED",
"updated_at": "2023-10-05T04:47:35.447Z"
}{
"error": {
"details": "Invalid sender_account.account_id value. Verify your account_id.",
"error_code": "INVALID_INPUT",
"message": "Invalid parameter value(s). Please review parameter inputs.",
"request_id": "{unique_id}",
"type": "API_ERROR"
}
}{
"error": {
"details": "<string>",
"error_code": "CREDENTIALS_INVALID",
"message": "<string>",
"request_id": "<string>",
"type": "LINKING_ERROR"
}
}{
"error": {
"details": "<string>",
"error_code": "CREDENTIALS_INVALID",
"message": "<string>",
"request_id": "<string>",
"type": "LINKING_ERROR"
}
}Mandates
Create Mandate with existing Sender Account
Create a Mandate (i.e. pre-authorization) that will be used to make payments, from an existing sender account (created via POST /payment_accounts).
Idempotency-Key header is required. This makes it safe to retry the request without re-triggering the underlying create Mandate operation. Any retries will return the same Mandate response as the first request using the same key.
Authorization: customer_token
Request parameters
Same as POST /mandates (Create Mandate), except for 2 differences:
- Do not provide a
senderobject - Instead, provide a
sender_accountobject, as specified below.
sender_account (object, required)
Details on the account sending the payment. This must reference an existing payment account, created via POST /payment_accounts.
Response fields
The response is a Mandate object.
Refer to Mandate object data model in GET /mandates/{mandate_id}.
POST
/
mandates
/
sender_account
Create Mandate with existing Sender Account
curl --request POST \
--url https://api.prod.finverse.net/mandates/sender_account \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"mandate_details": {
"currency": "<string>",
"description": "<string>",
"end_date": "2023-12-25",
"mandate_bank_reference": "<string>",
"start_date": "2023-12-25"
},
"recipient_account": {
"account_id": "<string>"
},
"sender_account": {
"account_id": "<string>"
},
"metadata": {}
}
'import requests
url = "https://api.prod.finverse.net/mandates/sender_account"
payload = {
"mandate_details": {
"currency": "<string>",
"description": "<string>",
"end_date": "2023-12-25",
"mandate_bank_reference": "<string>",
"start_date": "2023-12-25"
},
"recipient_account": { "account_id": "<string>" },
"sender_account": { "account_id": "<string>" },
"metadata": {}
}
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({
mandate_details: {
currency: '<string>',
description: '<string>',
end_date: '2023-12-25',
mandate_bank_reference: '<string>',
start_date: '2023-12-25'
},
recipient_account: {account_id: '<string>'},
sender_account: {account_id: '<string>'},
metadata: {}
})
};
fetch('https://api.prod.finverse.net/mandates/sender_account', 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.prod.finverse.net/mandates/sender_account",
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([
'mandate_details' => [
'currency' => '<string>',
'description' => '<string>',
'end_date' => '2023-12-25',
'mandate_bank_reference' => '<string>',
'start_date' => '2023-12-25'
],
'recipient_account' => [
'account_id' => '<string>'
],
'sender_account' => [
'account_id' => '<string>'
],
'metadata' => [
]
]),
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.prod.finverse.net/mandates/sender_account"
payload := strings.NewReader("{\n \"mandate_details\": {\n \"currency\": \"<string>\",\n \"description\": \"<string>\",\n \"end_date\": \"2023-12-25\",\n \"mandate_bank_reference\": \"<string>\",\n \"start_date\": \"2023-12-25\"\n },\n \"recipient_account\": {\n \"account_id\": \"<string>\"\n },\n \"sender_account\": {\n \"account_id\": \"<string>\"\n },\n \"metadata\": {}\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.prod.finverse.net/mandates/sender_account")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"mandate_details\": {\n \"currency\": \"<string>\",\n \"description\": \"<string>\",\n \"end_date\": \"2023-12-25\",\n \"mandate_bank_reference\": \"<string>\",\n \"start_date\": \"2023-12-25\"\n },\n \"recipient_account\": {\n \"account_id\": \"<string>\"\n },\n \"sender_account\": {\n \"account_id\": \"<string>\"\n },\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.prod.finverse.net/mandates/sender_account")
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 \"mandate_details\": {\n \"currency\": \"<string>\",\n \"description\": \"<string>\",\n \"end_date\": \"2023-12-25\",\n \"mandate_bank_reference\": \"<string>\",\n \"start_date\": \"2023-12-25\"\n },\n \"recipient_account\": {\n \"account_id\": \"<string>\"\n },\n \"sender_account\": {\n \"account_id\": \"<string>\"\n },\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"fees": [],
"mandate_details": {
"currency": "HKD",
"description": "Test Mandate",
"end_date": "2024-03-01",
"start_date": "2023-10-05",
"transaction_limits": {
"max_period_amount": 10000,
"max_period_count": 10,
"max_transaction_amount": 10000,
"period": "MONTHLY"
}
},
"mandate_id": "01HBZ2K7Y2B7C7TDM7C3BBBZCG",
"metadata": {
"employer_name": "Apple Inc",
"key": "value"
},
"payment_method_id": "01HJ5XHPFR9SDAPZ0Y143R6XCF",
"recipient": {
"name": "John Doe"
},
"recipient_account": {
"account_id": "01GMC9RSPCHAJ9ER9A4JR4AP6X",
"account_type": "SETTLEMENT_ACCOUNT"
},
"sender": {
"external_user_id": "unique_user_id_1695719460",
"name": "John Doe",
"user_details": [
{
"details_type": "HK_ID",
"values": [
"01HB8C32WGQNSP3MMN4P49YT70"
]
}
],
"user_id": "01HB8C32TD4V1RSB1HCZREXVMH",
"user_type": "INDIVIDUAL"
},
"sender_account": {
"account_id": "01HBA46Z9JVR54MWR0YDEZX3XK",
"account_number": {
"number": "01HBA46ZEA306KKDPVE80MYME5",
"type": "LOCAL"
},
"account_number_masked": "132XXXXXXXX4343",
"account_type": "EXTERNAL_ACCOUNT",
"accountholder_name": "01HBA46ZFFKHXQ4F60HRGH9HF4",
"institution_id": "testbank-dbs-hk",
"user_id": "01HB8C32TD4V1RSB1HCZREXVMH"
},
"status": "AUTHORIZATION_REQUIRED",
"updated_at": "2023-10-05T04:47:35.447Z"
}{
"error": {
"details": "Invalid sender_account.account_id value. Verify your account_id.",
"error_code": "INVALID_INPUT",
"message": "Invalid parameter value(s). Please review parameter inputs.",
"request_id": "{unique_id}",
"type": "API_ERROR"
}
}{
"error": {
"details": "<string>",
"error_code": "CREDENTIALS_INVALID",
"message": "<string>",
"request_id": "<string>",
"type": "LINKING_ERROR"
}
}{
"error": {
"details": "<string>",
"error_code": "CREDENTIALS_INVALID",
"message": "<string>",
"request_id": "<string>",
"type": "LINKING_ERROR"
}
}Authorizations
The access token received from the authorization server in the OAuth 2.0 flow.
Headers
A random key provided by the customer, per unique payment. The purpose for the Idempotency key is to allow safe retrying without the operation being performed multiple times.
Body
application/json
request body for creating mandate
Response
Success
Show child attributes
Show child attributes
Finverse Mandate ID (ULID)
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Mandate status
Available options:
AUTHORIZATION_REQUIRED, AUTHORIZING, PROCESSING, SUBMITTED, SUCCEEDED, FAILED, REVOKED, READY_TO_SUBMIT, CLOSED, CANCELLED Timestamp in ISO format (YYYY-MM-DDTHH:MM:SS.SSSZ)
Timestamp in ISO format (YYYY-MM-DDTHH:MM:SS.SSSZ)
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Additional attributes of the mandate in key:value format (e.g. mandate_internal_id: 1234). It supports up to 10 key:value pairs, whereas the key and value supports up to 50 and 1000 characters respectively.
Show child attributes
Show child attributes
Finverse Payment Method ID (ULID)
Show child attributes
Show child attributes
Show child attributes
Show child attributes