Authorize Mandate

curl --request POST \
  --url https://api.prod.finverse.net/mandates/{mandateId}/authorize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "enduser_consent": true
}
'

import requests

url = "https://api.prod.finverse.net/mandates/{mandateId}/authorize"

payload = { "enduser_consent": True }
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({enduser_consent: true})
};

fetch('https://api.prod.finverse.net/mandates/{mandateId}/authorize', 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/{mandateId}/authorize",
  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([
    'enduser_consent' => true
  ]),
  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/{mandateId}/authorize"

	payload := strings.NewReader("{\n  \"enduser_consent\": true\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/{mandateId}/authorize")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"enduser_consent\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.prod.finverse.net/mandates/{mandateId}/authorize")

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  \"enduser_consent\": true\n}"

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

{
  "fees": [],
  "mandate_details": {
    "collection_entity_name": "Finverse Technologies Limited",
    "currency": "HKD",
    "description": "Test Mandate",
    "end_date": "2024-03-01",
    "processor_entity_name": "Finverse Technologies Limited",
    "start_date": "2023-10-06",
    "transaction_limits": {
      "max_period_amount": 10000,
      "max_period_count": 10,
      "max_transaction_amount": 10000,
      "period": "MONTHLY"
    }
  },
  "mandate_id": "01HC1H0S5V7J3Q2GN5CBW7T3VZ",
  "metadata": {
    "employer_name": "Apple Inc",
    "key": "value"
  },
  "payment_method_id": "01HJ5XHXWYMTBC50V26Q0T2BG2",
  "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": "PROCESSING",
  "updated_at": "2023-10-06T03:38:20.444Z"
}

Mandates

Authorize Mandate

Mark the Mandate as authorized after obtaining end-user consent outside of the Finverse Link UI.

Access: This flow is available on demand for Finverse customers who do not need the Finverse UI to collect the user’s sender account details and obtain end-user consent. Contact [email protected] to request access.

To use this flow, the Customer must first complete the following API calls:

Create a Payment User for the sender
Create a Payment Account for the sender
Create a Mandate with the existing sender account (Payment Account of the user). Refer to: POST /mandates/sender_account.
Mark the Mandate as authorized (this API call).

Authorization: customer_token.

POST

mandates

{mandateId}

authorize

Authorize Mandate

curl --request POST \
  --url https://api.prod.finverse.net/mandates/{mandateId}/authorize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "enduser_consent": true
}
'

import requests

url = "https://api.prod.finverse.net/mandates/{mandateId}/authorize"

payload = { "enduser_consent": True }
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({enduser_consent: true})
};

fetch('https://api.prod.finverse.net/mandates/{mandateId}/authorize', 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/{mandateId}/authorize",
  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([
    'enduser_consent' => true
  ]),
  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/{mandateId}/authorize"

	payload := strings.NewReader("{\n  \"enduser_consent\": true\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/{mandateId}/authorize")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"enduser_consent\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.prod.finverse.net/mandates/{mandateId}/authorize")

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  \"enduser_consent\": true\n}"

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

{
  "fees": [],
  "mandate_details": {
    "collection_entity_name": "Finverse Technologies Limited",
    "currency": "HKD",
    "description": "Test Mandate",
    "end_date": "2024-03-01",
    "processor_entity_name": "Finverse Technologies Limited",
    "start_date": "2023-10-06",
    "transaction_limits": {
      "max_period_amount": 10000,
      "max_period_count": 10,
      "max_transaction_amount": 10000,
      "period": "MONTHLY"
    }
  },
  "mandate_id": "01HC1H0S5V7J3Q2GN5CBW7T3VZ",
  "metadata": {
    "employer_name": "Apple Inc",
    "key": "value"
  },
  "payment_method_id": "01HJ5XHXWYMTBC50V26Q0T2BG2",
  "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": "PROCESSING",
  "updated_at": "2023-10-06T03:38:20.444Z"
}

Authorizations

Authorization

string

header

required

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

Path Parameters

mandateId

string

required

The mandate_id that is being authorized

Body

application/json

request body for authorizing a mandate

Whether a consent was provided by the enduser to authorize a mandate

Response

Successful

mandate_details

object

required

Details on the mandate

Show child attributes

mandate_id

string

required

Finverse Mandate ID for this mandate. Always unique. Creating a mandate with different idempotency keys will result in two mandates with different IDs.

recipient

object

required

Details on the recipient of the payment

Show child attributes

sender

object

required

Details on the sender of the payment

Show child attributes

status

enum<string>

required

Current status of the mandate. Possible values: AUTHORIZATION_REQUIRED, PROCESSING, READY_TO_SUBMIT, SUBMITTED, SUCCEEDED, CANCELLED, CLOSED, FAILED Note: CLOSED occurs when a draft Mandate is created by a Finverse Payment Link (with status AUTHORIZATION_REQUIRED), and the user then drops-off or creates a new Payment Method or Mandate. In these cases, Finverse closes the draft Mandate in order to associate a new Payment Method / Mandate with the same Payment Link.

Available options:

AUTHORIZATION_REQUIRED,

AUTHORIZING,

PROCESSING,

SUBMITTED,

SUCCEEDED,

FAILED,

REVOKED

updated_at

string<date-time>

required

Timestamp of the last update to the mandate's record

created_at

string<date-time>

Timestamp when the mandate was first created

error

object

Details on why the mandate failed (returned when status = FAILED). Note: this is used to detail any asynchronous e errors occuring after mandate creation; any synchronous errors (e.g. API validation errors) will instead be returned directly during POST /mandates.

Show child attributes

fees

object[]

Details on the fee(s) to be charged

Show child attributes

metadata

object

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

Show child attributes

payment_method_id

string

Finverse Payment Method ID for this mandate, used to create payments using the mandate (see POST /payments). Always unique. Creating a mandate with different idempotency keys will result in two mandates with different IDs.

recipient_account

object

Details on the recipient's account for the payment (i.e. the Customer App's settlement account at Finverse)

Show child attributes

sender_account

object

Details on the sender's source institution and account, which is funding the payment

Show child attributes