curl --request POST \
  --url https://api.prod.finverse.net/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 6969,
  "currency": "AUD",
  "metadata": {
    "key": "value",
    "branch": "branch1"
  },
  "payment_details": {
    "description": "Test payment",
    "external_transaction_reference": "{{$timestamp}}"
  },
  "payment_method_id": "{{payment_method_id}}"
}
'

{
  "amount": 500,
  "created_at": "2024-08-16T15:27:41.534Z",
  "currency": "HKD",
  "fees": [
    {
      "amount": 500,
      "currency": "HKD",
      "paid_by": "RECIPIENT",
      "paid_by_account_id": "01H5VH5YCFDVH80YZ8D0TG3HET"
    }
  ],
  "metadata": {
    "employer_name": "Apple Inc",
    "key": "value"
  },
  "payment_details": {
    "collection_entity_name": "Finverse Technologies Limited",
    "description": "Test payment",
    "external_transaction_reference": "1723822061",
    "mandate_id": "01HW1W33TGWTZHNE0CR4VNB4WB",
    "processor_entity_name": "Finverse Technologies Limited",
    "transaction_reference_id": "1723822061"
  },
  "payment_id": "01J5DWTDMNNGT58N913GSZPKPP",
  "payment_method_id": "01HW1W33X48J0SVTMM344K6SPD",
  "recipient": {
    "name": "Demo App"
  },
  "recipient_account": {
    "account_id": "01H5VH5YCFDVH80YZ8D0TG3HET",
    "account_type": "SETTLEMENT_ACCOUNT"
  },
  "sender": {
    "external_user_id": "user_id_1||1713754935",
    "name": "John Doe",
    "user_details": [],
    "user_id": "01HW1W246Y9MSN22T50J3CD04T",
    "user_type": "INDIVIDUAL"
  },
  "sender_account": {
    "account_id": "01HW1W3MH68XRDS9W2XFZMJJEP",
    "account_number": {
      "number": "01HW1W3MQ339JXA66JF8P62042",
      "type": "LOCAL"
    },
    "account_number_masked": "939XXXXXX94",
    "account_type": "EXTERNAL_ACCOUNT",
    "accountholder_name": "01HW1W3MP3VMSTFR7FSB2YJ50F",
    "bank_code": "420",
    "institution_id": "testbank-dbs-hk",
    "institution_name": "Testbank (HK) Payments - Personal",
    "user_id": "01HW1W246Y9MSN22T50J3CD04T"
  },
  "status": "PROCESSING",
  "type": "MANDATE",
  "updated_at": "2024-08-16T15:27:41.534Z"
}

Payment operations

Create Payment

Create new Payment (off-session) for an existing payment_method_id.

To iniitate an off-session payment, a user (sender) must have autopay_consent = true (set via the Payment Link flow or Mandate setup flow), and a valid payment method (Mandate or Card).

To initiate an on-session payment for a user (sender) with a stored payment method but autopay_consent = false, use POST /payment_links instead (passing the user’s external_user_id).

Authorization: customer_token

Request headers

payment_details (object, required)

Details describing the payment.

Response fields

The response is a Payment object.

Refer to Payment object data model in GET /payments/{payment_id}.

POST

payments

curl --request POST \
  --url https://api.prod.finverse.net/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 6969,
  "currency": "AUD",
  "metadata": {
    "key": "value",
    "branch": "branch1"
  },
  "payment_details": {
    "description": "Test payment",
    "external_transaction_reference": "{{$timestamp}}"
  },
  "payment_method_id": "{{payment_method_id}}"
}
'

{
  "amount": 500,
  "created_at": "2024-08-16T15:27:41.534Z",
  "currency": "HKD",
  "fees": [
    {
      "amount": 500,
      "currency": "HKD",
      "paid_by": "RECIPIENT",
      "paid_by_account_id": "01H5VH5YCFDVH80YZ8D0TG3HET"
    }
  ],
  "metadata": {
    "employer_name": "Apple Inc",
    "key": "value"
  },
  "payment_details": {
    "collection_entity_name": "Finverse Technologies Limited",
    "description": "Test payment",
    "external_transaction_reference": "1723822061",
    "mandate_id": "01HW1W33TGWTZHNE0CR4VNB4WB",
    "processor_entity_name": "Finverse Technologies Limited",
    "transaction_reference_id": "1723822061"
  },
  "payment_id": "01J5DWTDMNNGT58N913GSZPKPP",
  "payment_method_id": "01HW1W33X48J0SVTMM344K6SPD",
  "recipient": {
    "name": "Demo App"
  },
  "recipient_account": {
    "account_id": "01H5VH5YCFDVH80YZ8D0TG3HET",
    "account_type": "SETTLEMENT_ACCOUNT"
  },
  "sender": {
    "external_user_id": "user_id_1||1713754935",
    "name": "John Doe",
    "user_details": [],
    "user_id": "01HW1W246Y9MSN22T50J3CD04T",
    "user_type": "INDIVIDUAL"
  },
  "sender_account": {
    "account_id": "01HW1W3MH68XRDS9W2XFZMJJEP",
    "account_number": {
      "number": "01HW1W3MQ339JXA66JF8P62042",
      "type": "LOCAL"
    },
    "account_number_masked": "939XXXXXX94",
    "account_type": "EXTERNAL_ACCOUNT",
    "accountholder_name": "01HW1W3MP3VMSTFR7FSB2YJ50F",
    "bank_code": "420",
    "institution_id": "testbank-dbs-hk",
    "institution_name": "Testbank (HK) Payments - Personal",
    "user_id": "01HW1W246Y9MSN22T50J3CD04T"
  },
  "status": "PROCESSING",
  "type": "MANDATE",
  "updated_at": "2024-08-16T15:27:41.534Z"
}

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 payment

amount

integer

required

Amount of the payment (in minor currency unit)

Example:

100

currency

string

required

Currency of the payment (e.g. HKD)

Maximum string length: 3

Example:

"HKD"

payment_details

object

required

Details on the payment

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. Required unless mandate_id is provided in payment_details.

Response

Successful

amount

integer

required

Amount of the payment (in minor currency unit)

Example:

100

amount_total_with_surcharge

integer

required

Total amount of the payment including any transaction fee surcharge_amount paid by the sender (in minor currency unit). See surcharge_amount on transaction fee surcharges.

Example:

100

surcharge_amount

integer

required

Transaction fee surcharge_amount paid by the sender, if any surcharge has been configured (in minor currency unit). Transaction fee surcharges are off by default, but can be set for specific payment methods, or for custom scenarios (e.g. based on transaction amount, payment flow, etc). Contact [email protected] to configure surcharges.

Example:

100

created_at

string<date-time>

Timestamp when the payment was first created

currency

string

Currency of the payment (e.g. HKD)

Example:

"HKD"

error

object

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

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_details

object

Details on the payment

Show child attributes

payment_id

string

Finverse Payment ID for this payment. Always unique. Creating a payment with different idempotency keys will result in two payments with different IDs.

payment_method

object

Details on the payment method

Show child attributes

payment_method_id

string

(TO BE DEPRECATED) Finverse unique ID for the payment method

recipient

object

Details on the recipient of the payment

Show child attributes

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

object

Details on the sender of the payment

Show child attributes

sender_account

object

(IN DEVELOPMENT) Details on the Sender's source institution and account, which is funding the payment

Show child attributes

status

enum<string>

Current status of the payment. Possible values: CREATED, AUTHORIZATION_REQUIRED, PROCESSING, SUBMITTED, EXECUTED, CANCELLED, FAILED

Available options:

AUTHORIZATION_REQUIRED,

AUTHORIZING,

PROCESSING,

SUBMITTED,

EXECUTED,

FAILED,

REVOKED,

CANCELLED,

CREATED

type

enum<string>

Specified payment type. Possible values: - CARD: payment via card gateway (e.g. Stripe) - MANDATE: direct debit bank payment - MANUAL: manual bank transfer (e.g. FPS, PayNow) - SINGLE: not used (reserved for future use)

Available options:

MANDATE,

SINGLE,

CARD,

MANUAL,

WALLET

updated_at

string<date-time>

Timestamp of the last update to the payment's record