curl --request POST \
  --url https://api.prod.finverse.net/payment_users/{paymentUserId}/payment_methods \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "mandate": {
    "mandate_details": {
      "dda_reference": "{{dda_reference}}",
      "currency": "SGD",
      "description": "Paper eGIRO Mandate",
      "transaction_limits": {
        "max_period_amount": 100000000,
        "max_period_count": 100000,
        "max_transaction_amount": 100000000,
        "period": "MONTHLY"
      }
    },
    "metadata": {
      "key": "value"
    },
    "recipient_account": {
      "account_id": "{{recipient_account_id}}"
    },
    "sender_account": {
      "account_id": "{{existing_sender_account_id2}}"
    },
    "status": "SUCCEEDED"
  },
  "payment_method_type": "MANDATE"
}
'

{
  "payment_methods": [
    {
      "mandate": {
        "created_at": "2024-03-22T05:30:07.606Z",
        "fees": [
          {
            "amount": 0,
            "currency": "HKD",
            "paid_by": "RECIPIENT",
            "paid_by_account_id": "01H2QD9W1SR1QN7JAMVNF4A6GC"
          }
        ],
        "mandate_details": {
          "collection_entity_name": "Finverse Technologies Limited",
          "currency": "HKD",
          "description": "Payment link mandate",
          "mandate_bank_reference": "01FHF1MEY9-VWNM-01FH",
          "processor_entity_name": "Finverse Technologies Limited",
          "start_date": "2024-03-22",
          "transaction_limits": {
            "max_transaction_amount": 100000000
          }
        },
        "mandate_id": "01HSJA64F1Q3NGVB3D94XFNHBD",
        "payment_method_id": "01HSJA64HAP8KVSXCMP6K7KQY2",
        "recipient": {
          "name": "REGRESSION"
        },
        "recipient_account": {
          "account_id": "01H2QD9W1SR1QN7JAMVNF4A6GC",
          "account_type": "SETTLEMENT_ACCOUNT"
        },
        "sender": {
          "external_user_id": "user_id_1||1711085382",
          "name": "John Doe",
          "user_details": [],
          "user_id": "01HSJA5TNAQSRZEZGX9KM3WPM8",
          "user_type": "INDIVIDUAL"
        },
        "sender_account": {
          "account_id": "01HSJA6HWKG3ENW4WV678APHHJ",
          "account_number": {
            "number": "01HSJA6HZW81QPCJXB48AW1FJ9",
            "type": "LOCAL"
          },
          "account_number_masked": "XX34",
          "account_type": "EXTERNAL_ACCOUNT",
          "accountholder_name": "01HSJA6HZEBEYWHZ56HSBGJWA7",
          "institution_id": "testbank-dbs-hk",
          "user_id": "01HSJA5TNAQSRZEZGX9KM3WPM8"
        },
        "status": "SUCCEEDED",
        "updated_at": "2024-03-22T05:30:06.686Z"
      },
      "payment_method_id": "01HSJA64HAP8KVSXCMP6K7KQY2",
      "payment_method_type": "MANDATE"
    }
  ],
  "sender": {
    "autopay_consent": true,
    "created_at": "2024-03-22T05:29:42.314Z",
    "external_user_id": "user_id_1||1711085382",
    "name": "John Doe",
    "updated_at": "2024-03-22T05:30:11.301Z",
    "user_details": [],
    "user_id": "01HSJA5TNAQSRZEZGX9KM3WPM8",
    "user_type": "INDIVIDUAL"
  }
}

Payment users

Create Payment Method: direct debit mandate

Note: this endpoint is primarily intended for migrating payment methods from other payment gateways into Finverse.

Manually register a Payment Method, referencing a valid card or direct debit mandate (already setup on a 3rd party payment gateway).

The fields required depend on whether the payment method to be registered is a card or direct debit mandate.

This request example creates a direct debit mandate. See the next requests for examples of creating a card payment method.

Access: This flow is available on demand for Finverse customers who want to directly create or migrate Payment Methods. Contact [email protected] to request access.

Authorization: customer_token

Request fields

Pass details of the card or mandate to be created.

card (object, conditionally required)

Details on the card authorized by the end-user.

mandate (object, conditionally required)

Details on the direct debit mandate authorized by the end-user.

mandate_details (object, required)

Details describing the Mandate.

recipient_account (object, required)

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

sender_account (object, required)

Details on the sender account of the payment (i.e. the payer’s originating account).

Response fields

Single Payment Method object containg details on the payment method authorized by the end-used (Card or Mandate).

card (object, conditional)

Details on the card authorized by the end-user.

card_details (object)

Additional details on the card.

sender (object)

The sender object includes a Payment User object for the sender of the payment. Refer to the Payment User data model in GET /payment_users/{payment_user_id} for details on the Payment User object.

Note: Some Payment User metadata fields are omitted for clarity (e.g. created_at, metadata, updated_at).

POST

payment_users

{paymentUserId}

payment_methods

curl --request POST \
  --url https://api.prod.finverse.net/payment_users/{paymentUserId}/payment_methods \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "mandate": {
    "mandate_details": {
      "dda_reference": "{{dda_reference}}",
      "currency": "SGD",
      "description": "Paper eGIRO Mandate",
      "transaction_limits": {
        "max_period_amount": 100000000,
        "max_period_count": 100000,
        "max_transaction_amount": 100000000,
        "period": "MONTHLY"
      }
    },
    "metadata": {
      "key": "value"
    },
    "recipient_account": {
      "account_id": "{{recipient_account_id}}"
    },
    "sender_account": {
      "account_id": "{{existing_sender_account_id2}}"
    },
    "status": "SUCCEEDED"
  },
  "payment_method_type": "MANDATE"
}
'

{
  "payment_methods": [
    {
      "mandate": {
        "created_at": "2024-03-22T05:30:07.606Z",
        "fees": [
          {
            "amount": 0,
            "currency": "HKD",
            "paid_by": "RECIPIENT",
            "paid_by_account_id": "01H2QD9W1SR1QN7JAMVNF4A6GC"
          }
        ],
        "mandate_details": {
          "collection_entity_name": "Finverse Technologies Limited",
          "currency": "HKD",
          "description": "Payment link mandate",
          "mandate_bank_reference": "01FHF1MEY9-VWNM-01FH",
          "processor_entity_name": "Finverse Technologies Limited",
          "start_date": "2024-03-22",
          "transaction_limits": {
            "max_transaction_amount": 100000000
          }
        },
        "mandate_id": "01HSJA64F1Q3NGVB3D94XFNHBD",
        "payment_method_id": "01HSJA64HAP8KVSXCMP6K7KQY2",
        "recipient": {
          "name": "REGRESSION"
        },
        "recipient_account": {
          "account_id": "01H2QD9W1SR1QN7JAMVNF4A6GC",
          "account_type": "SETTLEMENT_ACCOUNT"
        },
        "sender": {
          "external_user_id": "user_id_1||1711085382",
          "name": "John Doe",
          "user_details": [],
          "user_id": "01HSJA5TNAQSRZEZGX9KM3WPM8",
          "user_type": "INDIVIDUAL"
        },
        "sender_account": {
          "account_id": "01HSJA6HWKG3ENW4WV678APHHJ",
          "account_number": {
            "number": "01HSJA6HZW81QPCJXB48AW1FJ9",
            "type": "LOCAL"
          },
          "account_number_masked": "XX34",
          "account_type": "EXTERNAL_ACCOUNT",
          "accountholder_name": "01HSJA6HZEBEYWHZ56HSBGJWA7",
          "institution_id": "testbank-dbs-hk",
          "user_id": "01HSJA5TNAQSRZEZGX9KM3WPM8"
        },
        "status": "SUCCEEDED",
        "updated_at": "2024-03-22T05:30:06.686Z"
      },
      "payment_method_id": "01HSJA64HAP8KVSXCMP6K7KQY2",
      "payment_method_type": "MANDATE"
    }
  ],
  "sender": {
    "autopay_consent": true,
    "created_at": "2024-03-22T05:29:42.314Z",
    "external_user_id": "user_id_1||1711085382",
    "name": "John Doe",
    "updated_at": "2024-03-22T05:30:11.301Z",
    "user_details": [],
    "user_id": "01HSJA5TNAQSRZEZGX9KM3WPM8",
    "user_type": "INDIVIDUAL"
  }
}

Authorizations

Authorization

string

header

required

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

Path Parameters

paymentUserId

string

required

Payment User ID

Body

application/json

payment_method_type

enum<string>

required

Available options:

CARD,

MANDATE

card

object

Show child attributes

integration_metadata

object

Show child attributes

mandate

object

Show child attributes

Response

Success (Mandate)

card

object

Card object Included only if payment_method_type = CARD.

Show child attributes

integration_metadata

object

Show child attributes

mandate

object

Mandate object. Refer to Mandate object data model in GET /mandates/{mandate_id}. Included only if payment_method_type = MANDATE.

Show child attributes

payment_method_id

string

Finverse unique ID for this payment method. If the Sender has autopay_consent = true , this ID can be used to trigger additional payments on-demand (see POST /payments).

payment_method_type

string

Type of payment method. Possible values: CARD, MANDATE.