Create Mandate

curl --request POST \
  --url https://api.prod.finverse.net/mandates \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --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": {
    "email": "[email protected]",
    "external_user_id": "<string>",
    "name": "<string>",
    "user_details": [
      {
        "values": [
          "<string>"
        ]
      }
    ]
  },
  "metadata": {}
}
'

import requests

url = "https://api.prod.finverse.net/mandates"

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": {
        "email": "[email protected]",
        "external_user_id": "<string>",
        "name": "<string>",
        "user_details": [{ "values": ["<string>"] }]
    },
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {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: {
      email: '[email protected]',
      external_user_id: '<string>',
      name: '<string>',
      user_details: [{values: ['<string>']}]
    },
    metadata: {}
  })
};

fetch('https://api.prod.finverse.net/mandates', 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",
  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' => [
        'email' => '[email protected]',
        'external_user_id' => '<string>',
        'name' => '<string>',
        'user_details' => [
                [
                                'values' => [
                                                                '<string>'
                                ]
                ]
        ]
    ],
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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"

	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\": {\n    \"email\": \"[email protected]\",\n    \"external_user_id\": \"<string>\",\n    \"name\": \"<string>\",\n    \"user_details\": [\n      {\n        \"values\": [\n          \"<string>\"\n        ]\n      }\n    ]\n  },\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	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")
  .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\": {\n    \"email\": \"[email protected]\",\n    \"external_user_id\": \"<string>\",\n    \"name\": \"<string>\",\n    \"user_details\": [\n      {\n        \"values\": [\n          \"<string>\"\n        ]\n      }\n    ]\n  },\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.prod.finverse.net/mandates")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
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\": {\n    \"email\": \"[email protected]\",\n    \"external_user_id\": \"<string>\",\n    \"name\": \"<string>\",\n    \"user_details\": [\n      {\n        \"values\": [\n          \"<string>\"\n        ]\n      }\n    ]\n  },\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "created_at": "2024-03-28T15:06:10.744Z",
  "fees": [],
  "mandate_details": {
    "currency": "HKD",
    "description": "Test Mandate",
    "end_date": "2024-12-01",
    "start_date": "2024-03-28",
    "transaction_limits": {
      "max_period_amount": 10000,
      "max_period_count": 10,
      "max_transaction_amount": 10000,
      "period": "MONTHLY"
    }
  },
  "mandate_id": "01HT2SHP6DQJ3A4MTR6V5RVDYR",
  "metadata": {
    "employer_name": "Apple Inc",
    "key": "value"
  },
  "payment_method_id": "01HT2SHPDAFZCHPVCDJ2Z99GX8",
  "recipient": {
    "name": "Demo App"
  },
  "recipient_account": {
    "account_id": "01H5VH5YCFDVH80YZ8D0TG3HET",
    "account_type": "SETTLEMENT_ACCOUNT"
  },
  "sender": {
    "external_user_id": "user_id_1",
    "name": "John Doe",
    "user_details": [
      {
        "details_type": "HK_ID",
        "values": [
          "01HT2SHPCXQNGDGEHTHXTKAB90"
        ]
      }
    ],
    "user_id": "01GWKTK0380NBRCV1B8D6N0SEH",
    "user_type": "INDIVIDUAL"
  },
  "status": "AUTHORIZATION_REQUIRED",
  "updated_at": "2024-03-28T15:06:10.730Z"
}

Mandates

Create Mandate

Create a Mandate (i.e. pre-authorization) that will be used to make payments, without any existing/known sender account details (the end-user will be requested to input these in the mandate authorization UI).

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

mandate_details (object, required)

Details describing the Mandate.

payment_schedule (object, optional)

RESERVED FOR FUTURE USE - Specifies scheduled auto-payments with the specified amounts and dates.

transaction_limits (object, optional)

Specifies custom limits on payment transactions executed under the Mandate.

recipient_account (object, required)

Details on the recipient account of the payment (i.e. the Customer App’s receiving account).

sender (object, required)

Details on the sender of the payment.

user_details (array of objects, optional)

Additional information about the user’s identity, used for validating any end-user submitted identity details in the Finverse Link UI.

Response fields

The response is a Mandate object.

Refer to Mandate object data model in GET /mandates/{mandate_id}.

POST

mandates

Create Mandate

curl --request POST \
  --url https://api.prod.finverse.net/mandates \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --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": {
    "email": "[email protected]",
    "external_user_id": "<string>",
    "name": "<string>",
    "user_details": [
      {
        "values": [
          "<string>"
        ]
      }
    ]
  },
  "metadata": {}
}
'

import requests

url = "https://api.prod.finverse.net/mandates"

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": {
        "email": "[email protected]",
        "external_user_id": "<string>",
        "name": "<string>",
        "user_details": [{ "values": ["<string>"] }]
    },
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {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: {
      email: '[email protected]',
      external_user_id: '<string>',
      name: '<string>',
      user_details: [{values: ['<string>']}]
    },
    metadata: {}
  })
};

fetch('https://api.prod.finverse.net/mandates', 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",
  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' => [
        'email' => '[email protected]',
        'external_user_id' => '<string>',
        'name' => '<string>',
        'user_details' => [
                [
                                'values' => [
                                                                '<string>'
                                ]
                ]
        ]
    ],
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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"

	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\": {\n    \"email\": \"[email protected]\",\n    \"external_user_id\": \"<string>\",\n    \"name\": \"<string>\",\n    \"user_details\": [\n      {\n        \"values\": [\n          \"<string>\"\n        ]\n      }\n    ]\n  },\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	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")
  .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\": {\n    \"email\": \"[email protected]\",\n    \"external_user_id\": \"<string>\",\n    \"name\": \"<string>\",\n    \"user_details\": [\n      {\n        \"values\": [\n          \"<string>\"\n        ]\n      }\n    ]\n  },\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.prod.finverse.net/mandates")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
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\": {\n    \"email\": \"[email protected]\",\n    \"external_user_id\": \"<string>\",\n    \"name\": \"<string>\",\n    \"user_details\": [\n      {\n        \"values\": [\n          \"<string>\"\n        ]\n      }\n    ]\n  },\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "created_at": "2024-03-28T15:06:10.744Z",
  "fees": [],
  "mandate_details": {
    "currency": "HKD",
    "description": "Test Mandate",
    "end_date": "2024-12-01",
    "start_date": "2024-03-28",
    "transaction_limits": {
      "max_period_amount": 10000,
      "max_period_count": 10,
      "max_transaction_amount": 10000,
      "period": "MONTHLY"
    }
  },
  "mandate_id": "01HT2SHP6DQJ3A4MTR6V5RVDYR",
  "metadata": {
    "employer_name": "Apple Inc",
    "key": "value"
  },
  "payment_method_id": "01HT2SHPDAFZCHPVCDJ2Z99GX8",
  "recipient": {
    "name": "Demo App"
  },
  "recipient_account": {
    "account_id": "01H5VH5YCFDVH80YZ8D0TG3HET",
    "account_type": "SETTLEMENT_ACCOUNT"
  },
  "sender": {
    "external_user_id": "user_id_1",
    "name": "John Doe",
    "user_details": [
      {
        "details_type": "HK_ID",
        "values": [
          "01HT2SHPCXQNGDGEHTHXTKAB90"
        ]
      }
    ],
    "user_id": "01GWKTK0380NBRCV1B8D6N0SEH",
    "user_type": "INDIVIDUAL"
  },
  "status": "AUTHORIZATION_REQUIRED",
  "updated_at": "2024-03-28T15:06:10.730Z"
}

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Headers

Idempotency-Key

string

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

mandate_details

object

required

Details on the mandate

Show child attributes

recipient_account

object

required

Details on the recipient of the payment (i.e. the Customer App's receiving account)

Show child attributes

sender

object

required

Details on the sender of the payment

Show child attributes

metadata

object

Customer-supplied attributes in key:value format. E.g. employer_name: Apple Inc

Show child attributes

Response

Successful

mandate_details

object

required

Show child attributes

mandate_id

string

required

Finverse Mandate ID (ULID)

recipient

object

required

Show child attributes

sender

object

required

Show child attributes

status

enum<string>

required

Mandate status

Available options:

AUTHORIZATION_REQUIRED,

AUTHORIZING,

PROCESSING,

SUBMITTED,

SUCCEEDED,

FAILED,

REVOKED,

READY_TO_SUBMIT,

CLOSED,

CANCELLED

updated_at

string<date-time>

required

Timestamp in ISO format (YYYY-MM-DDTHH:MM:SS.SSSZ)

created_at

string<date-time>

Timestamp in ISO format (YYYY-MM-DDTHH:MM:SS.SSSZ)

error

object

Show child attributes

fees

object[]

Show child attributes

metadata

object

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

payment_method_id

string

Finverse Payment Method ID (ULID)

recipient_account

object

Show child attributes

sender_account

object

Show child attributes