Update Payment User

curl --request POST \
  --url https://api.prod.finverse.net/payment_users/{paymentUserId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "autopay_consent": true,
  "email": "<string>",
  "metadata": {},
  "name": "<string>",
  "next_bill_update": "2023-11-07T05:31:56Z"
}
'

import requests

url = "https://api.prod.finverse.net/payment_users/{paymentUserId}"

payload = {
    "autopay_consent": True,
    "email": "<string>",
    "metadata": {},
    "name": "<string>",
    "next_bill_update": "2023-11-07T05:31:56Z"
}
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({
    autopay_consent: true,
    email: '<string>',
    metadata: {},
    name: '<string>',
    next_bill_update: '2023-11-07T05:31:56Z'
  })
};

fetch('https://api.prod.finverse.net/payment_users/{paymentUserId}', 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/payment_users/{paymentUserId}",
  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([
    'autopay_consent' => true,
    'email' => '<string>',
    'metadata' => [
        
    ],
    'name' => '<string>',
    'next_bill_update' => '2023-11-07T05:31:56Z'
  ]),
  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/payment_users/{paymentUserId}"

	payload := strings.NewReader("{\n  \"autopay_consent\": true,\n  \"email\": \"<string>\",\n  \"metadata\": {},\n  \"name\": \"<string>\",\n  \"next_bill_update\": \"2023-11-07T05:31:56Z\"\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/payment_users/{paymentUserId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"autopay_consent\": true,\n  \"email\": \"<string>\",\n  \"metadata\": {},\n  \"name\": \"<string>\",\n  \"next_bill_update\": \"2023-11-07T05:31:56Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.prod.finverse.net/payment_users/{paymentUserId}")

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  \"autopay_consent\": true,\n  \"email\": \"<string>\",\n  \"metadata\": {},\n  \"name\": \"<string>\",\n  \"next_bill_update\": \"2023-11-07T05:31:56Z\"\n}"

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

{
  "autopay_consent": true,
  "created_at": "2024-10-16T08:57:06.155Z",
  "email": "[email protected]",
  "external_user_id": "unique_user_id_1729069025",
  "metadata": {
    "employer_name": "Apple Inc",
    "key": "value"
  },
  "name": "John Doe",
  "next_bill_update": "2024-12-02T00:06:00.000Z",
  "updated_at": "2024-10-16T08:57:59.092Z",
  "user_details": [
    {
      "details_type": "HK_ID",
      "values": [
        "01JAA8Q2TW1S7K84D8YCHXM0KP"
      ]
    }
  ],
  "user_id": "01JAA8Q2PATMCX4V8M0KKMYW1C",
  "user_type": "INDIVIDUAL"
}

{
  "error": {
    "details": "unsupported field external_user_id supplied for update",
    "error_code": "INVALID_INPUT",
    "message": "Invalid parameter value(s). Please review parameter inputs.",
    "request_id": "1729069151",
    "type": "API_ERROR"
  }
}

{
  "error": {
    "details": "<string>",
    "error_code": "CREDENTIALS_INVALID",
    "message": "<string>",
    "request_id": "<string>",
    "type": "LINKING_ERROR"
  }
}

Payment users

Update Payment User

Update (PATCH) an existing Payment User, identified by the user’s Finverse user_id.

Access: This flow is available on demand for Finverse customers who want to directly manage Payment Users and Payment Accounts. Contact [email protected] to request access.

Authorization: customer_token

Implementation guidance

Autopay consent handling: be careful when updating the value of a user’s autopay_consent field. Key considerations:

The autopay_consent field should only be set to true if the user has specifically agreed to autopay future bills. We recommend preserving auditable evidence that users have provided this consent (e.g. in your logs or database records), which may be later requested by payment gateways or banks in the event of user billing disputes.
User notifications of change to autopay_consent****: Finverse will send an email notification to the user’s email each time the autopay_consent value is changed (e.g. from true to false, or false to true), to ensure that users are aware about whether their bills will be autopaid.
Autopay downstream handling: the way autopay_consent impacts future bill collections depends on your specific integration with Finverse.
1. If you have enabled a pre-built Finverse autopay integration (e.g. via Xero invoices, Sitelink/Rapidstor tenant ledgers, Storeganise invoices), Finverse will automatically handle autopayments on each bill due date for any users where (i) autopay_consent = true, and (ii) the user has at least 1 valid payment method.
2. If you are using a custom Finverse autopay integration, you need to initiate your own collection payment on your desired due date using the Finverse API, via POST /payments. Depending on your Customer App’s configuration, Finverse may verify that the user’s autopay_consent = true before processing each payment.

Request body

Only the selected fields below can currently be updated. Any omitted fields will remain unchanged.

The following fields are non-editable. Attempting to edit these will return an API error:

created_at, external_user_id, integration_metadata, updated_at, user_details, user_id

Response fields

The response is the updated Payment User object.

Refer to Payment User object data model in GET /payment_users/{user_id}.

POST

payment_users

{paymentUserId}

Update Payment User

curl --request POST \
  --url https://api.prod.finverse.net/payment_users/{paymentUserId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "autopay_consent": true,
  "email": "<string>",
  "metadata": {},
  "name": "<string>",
  "next_bill_update": "2023-11-07T05:31:56Z"
}
'

import requests

url = "https://api.prod.finverse.net/payment_users/{paymentUserId}"

payload = {
    "autopay_consent": True,
    "email": "<string>",
    "metadata": {},
    "name": "<string>",
    "next_bill_update": "2023-11-07T05:31:56Z"
}
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({
    autopay_consent: true,
    email: '<string>',
    metadata: {},
    name: '<string>',
    next_bill_update: '2023-11-07T05:31:56Z'
  })
};

fetch('https://api.prod.finverse.net/payment_users/{paymentUserId}', 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/payment_users/{paymentUserId}",
  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([
    'autopay_consent' => true,
    'email' => '<string>',
    'metadata' => [
        
    ],
    'name' => '<string>',
    'next_bill_update' => '2023-11-07T05:31:56Z'
  ]),
  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/payment_users/{paymentUserId}"

	payload := strings.NewReader("{\n  \"autopay_consent\": true,\n  \"email\": \"<string>\",\n  \"metadata\": {},\n  \"name\": \"<string>\",\n  \"next_bill_update\": \"2023-11-07T05:31:56Z\"\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/payment_users/{paymentUserId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"autopay_consent\": true,\n  \"email\": \"<string>\",\n  \"metadata\": {},\n  \"name\": \"<string>\",\n  \"next_bill_update\": \"2023-11-07T05:31:56Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.prod.finverse.net/payment_users/{paymentUserId}")

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  \"autopay_consent\": true,\n  \"email\": \"<string>\",\n  \"metadata\": {},\n  \"name\": \"<string>\",\n  \"next_bill_update\": \"2023-11-07T05:31:56Z\"\n}"

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

{
  "autopay_consent": true,
  "created_at": "2024-10-16T08:57:06.155Z",
  "email": "[email protected]",
  "external_user_id": "unique_user_id_1729069025",
  "metadata": {
    "employer_name": "Apple Inc",
    "key": "value"
  },
  "name": "John Doe",
  "next_bill_update": "2024-12-02T00:06:00.000Z",
  "updated_at": "2024-10-16T08:57:59.092Z",
  "user_details": [
    {
      "details_type": "HK_ID",
      "values": [
        "01JAA8Q2TW1S7K84D8YCHXM0KP"
      ]
    }
  ],
  "user_id": "01JAA8Q2PATMCX4V8M0KKMYW1C",
  "user_type": "INDIVIDUAL"
}

{
  "error": {
    "details": "unsupported field external_user_id supplied for update",
    "error_code": "INVALID_INPUT",
    "message": "Invalid parameter value(s). Please review parameter inputs.",
    "request_id": "1729069151",
    "type": "API_ERROR"
  }
}

{
  "error": {
    "details": "<string>",
    "error_code": "CREDENTIALS_INVALID",
    "message": "<string>",
    "request_id": "<string>",
    "type": "LINKING_ERROR"
  }
}

Authorizations

Authorization

string

header

required

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

Path Parameters

paymentUserId

string

required

Body

application/json

request body for updating payment user

string | null

Maximum string length: 256

metadata

object | null

Show child attributes

name

string | null

next_bill_update

string<date-time> | null

user_type

enum<string> | null

Available options:

INDIVIDUAL,

BUSINESS

Response

Success

Flag indicating whether the user has agreed to future (on-demand) payments of bills/invoices owed by the user. This consent is usually collected in the Payment Link flow. Value is false by default, unless: (i) the user enrolled into Autopay in the Payment Link UI, (ii) a Payment LInk was created with the configuration payment_setup_options.future_payments = AUTOPAY, (iii) the Payment User was created with autopay_consent = true using the Create Payment User API (POST /payment_users).

Example:

false

created_at

string<date-time>

Timestamp when the Payment User object was first created

string

Payment User's contact email, used for Finverse notifications. To ensure a smooth payment experience for end-users and to avoid support tickets or disputes, we strongly recommend enabling Finverse notifications by providing the end-user's email. Finverse sends email notifications for: - Changes to stored payment methods (e.g. direct debit mandate or card) - Changes to user autopay consent - Executed payments (except card payments via Stripe, since Stripe sends its own notifications). Contact [email protected] for the full list of email notifications sent by Finverse.

external_user_id

string

Customer App's unique ID for the user. This ID is used to identify returning users across user sessions and load the user's previously stored Payment Method and settings. For example, a returning user can: - Directly pay a Payment Link (in mode= payment) using their stored Payment Method, without re-entering payment details. - Use a Payment Link to edit their stored Payment Method. - Use a Payment Link to turn Autopay on/off (by editing their Autopay consent), if allowed by the Customer App.

integration_metadata

object

Show child attributes

metadata

object

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

Show child attributes

name

string

User's name or nickname (note: this does not need to exactly match the accountholder name of the user's account; however accountholder name inputs may be verified against this value).

next_bill_update

string<date-time> | null

Timestamp when Finverse is scheduled to attempt to fetch the next bill/invoice for this user. Bill/invoice ingestion is one of the available methods for Finverse to initiate Autopay bill collections on each bill due date, using the user's saved payment method(s). Note: bills will only be fetched if the Customer App has configured a 3rd party ERP/CRM or Accounting integration, enabling Finverse to fetch bill/invoice data from the 3rd party source (e.g. Xero, RapidStor). Contact [email protected] to discuss 3rd party bill/invoice integrations and Autopay flows.

updated_at

string<date-time>

Timestamp when the Payment User object was last updated

user_details

object[]

Additional information about the user's identity

Show child attributes

user_id

string

Finverse unique ID for the user.

user_type

enum<string>

Type of user (used to determine what user authentication inputs are required, e.g. individual ID vs. company registration details). Possible values: INDIVIDUAL, BUSINESS

Available options:

INDIVIDUAL,

BUSINESS