Create New Payment Setting

curl --request POST \
  --url https://api.royalti.io/payment-setting \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Primary Bank Account",
  "type": "BankWireTransfer",
  "settings": {
    "bankName": "Bank of Example",
    "accountNumber": "123456789",
    "bankCode": "987654",
    "country": "USA",
    "countryCode": "US",
    "currency": "USD"
  },
  "isDefault": true,
  "memo": "Main operational account",
  "user": ""
}
'

{
  "status": "success",
  "message": "Payment setting created successfully",
  "paymentSetting": {
    "id": "24d2c371-4a7a-4acd-b4aa-d3eb3bebd8fa",
    "name": "Primary Bank Account",
    "type": "BankWireTransfer",
    "settings": {
      "bankName": "Bank of Example",
      "accountNumber": "123456789",
      "bankCode": "987654",
      "country": "USA",
      "countryCode": "US",
      "currency": "USD"
    },
    "isDefault": true,
    "memo": "Main operational account",
    "createdAt": "2023-11-22T20:48:36.034Z",
    "updatedAt": "2023-11-22T20:48:36.034Z"
  }
}

{
  "message": "Validation failed",
  "errors": [
    "Name is required",
    "Invalid payment type"
  ]
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": [
      "<string>"
    ]
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": [
      "<string>"
    ]
  }
}

POST

payment-setting

curl --request POST \
  --url https://api.royalti.io/payment-setting \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Primary Bank Account",
  "type": "BankWireTransfer",
  "settings": {
    "bankName": "Bank of Example",
    "accountNumber": "123456789",
    "bankCode": "987654",
    "country": "USA",
    "countryCode": "US",
    "currency": "USD"
  },
  "isDefault": true,
  "memo": "Main operational account",
  "user": ""
}
'

{
  "status": "success",
  "message": "Payment setting created successfully",
  "paymentSetting": {
    "id": "24d2c371-4a7a-4acd-b4aa-d3eb3bebd8fa",
    "name": "Primary Bank Account",
    "type": "BankWireTransfer",
    "settings": {
      "bankName": "Bank of Example",
      "accountNumber": "123456789",
      "bankCode": "987654",
      "country": "USA",
      "countryCode": "US",
      "currency": "USD"
    },
    "isDefault": true,
    "memo": "Main operational account",
    "createdAt": "2023-11-22T20:48:36.034Z",
    "updatedAt": "2023-11-22T20:48:36.034Z"
  }
}

{
  "message": "Validation failed",
  "errors": [
    "Name is required",
    "Invalid payment type"
  ]
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": [
      "<string>"
    ]
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": [
      "<string>"
    ]
  }
}

This endpoint requires authentication. Include your Bearer token in the Authorization header.

Description

/payment-setting/ This endpoint is responsible for creating a new payment setting. Authorization:

Required role: user or higher

Method:
POST Request Payload:

Field	Type	Required	Description
name	string	Yes	The name of the payment setting
type	string	Yes	The type of the payment setting
settings	object	Yes	The settings/configuration of the payment setting. Some of the sample properties are “accountName”, “accountNumber”, “bankName”, “routingNumber”, “swiftCode”, “IBAN”, indicating details related to the payment method configuration
isDefault	boolean	No	Indicates whether the payment setting is the default one
memo	string	No	Any additional notes or comments about the payment setting
user	string	No	TenantUserId of the user, used when setting up payment settings for other users (admin/owner only)

Paystack side effect on BankWireTransfer settings: if the workspace has Paystack enabled, creating a BankWireTransfer setting triggers a live Paystack transfer-recipient resolution before the row is saved. Royalti first looks for a cached PaystackRecipientCode on another setting in the same workspace with a matching accountNumber/bankCode; if none exists, it calls Paystack to create a new transfer recipient and stores the returned code on settings.PaystackRecipientCode. For NGN accounts (settings.currency: NGN or settings.countryCode: NG), a failure to resolve or create the recipient makes the whole request fail with 400 — this is a live external-API call on an otherwise generic CRUD endpoint, not a background/best-effort step.

Request Body Examples

Bank Wire Transfer:

{
  "name": "Primary Bank Account",
  "type": "BankWireTransfer",
  "settings": {
    "bankName": "Bank of Example",
    "accountNumber": "123456789",
    "bankCode": "987654",
    "country": "USA",
    "countryCode": "US",
    "currency": "USD"
  },
  "isDefault": true,
  "memo": "Main operational account"
}

PayPal:

{
  "name": "Primary PayPal Account",
  "type": "PayPal",
  "settings": {
    "paypalEmail": "example@paypal.com",
    "country": "USA",
    "countryCode": "US",
    "currency": "USD"
  },
  "isDefault": true,
  "memo": "Main PayPal account"
}

Code Examples

const response = await fetch('https://api.royalti.io/payment-setting', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "name": "sample-name",
    "type": "sample-type",
    "settings": {},
    "isDefault": true,
    "user": "sample-user",
    "memo": "sample-memo"
  })
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
  'https://api.royalti.io/payment-setting',
  headers={
    'Authorization': f'Bearer {token}'
  },
  json={"name":"sample-name","type":"sample-type","settings":{},"isDefault":true,"user":"sample-user","memo":"sample-memo"}
)

data = response.json()
print(data)

curl -X POST https://api.royalti.io/payment-setting \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"sample-name","type":"sample-type","settings":{},"isDefault":true,"user":"sample-user","memo":"sample-memo"}'

Authorizations

Authorization

string

header

required

JWT Authorization header using the Bearer scheme. Format: "Bearer {token}"

Body

application/json

name

string

required

The name of the payment setting

type

enum<string>

required

The type of the payment setting

Available options:

BankWireTransfer,

PayPal,

Card,

Crypto

settings

object

required

The settings/configuration of the payment setting

isDefault

boolean

default:false

Indicates whether the payment setting is the default one

user

string

UserId of the user who created the payment setting, used when setting up payments settings for other used

memo

string

Any additional notes or comments about the payment setting

Response

Payment setting created successfully

status

string

message

string

paymentSetting

object

Show child attributes

​Description

​Request Body Examples

​Code Examples

Authorizations

Body

Response

Description

Request Body Examples

Code Examples