Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

groups

Create New Payment Group

post
/payments/groups

The Create A Payment Group API is designed to help users organize and manage payments by grouping related payment instructions. This API allows developers to create a new payment group within an account. A payment group is associated with a specific wallet and is used to organize and manage multiple payment instructions under a single group. This feature is particularly useful for streamlining payment operations based on various criteria such as time, location, or business unit.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body
namestringRequired

A label to identify the group. This name should be unique within the account to avoid confusion with other groups (e.g., "February USD cycle").

descriptionstringOptional

A short description of the group that provides context or notes on its purpose.

walletstringRequired

The Wallet ID linked to this group. All payments within this group will be associated with this wallet (e.g., "f6b2776d-53f4-404e-a690-c3766a91d43a").

Responses
200

Successful response

application/json
namestring · min: 1Optional

The name of the group.

typestringOptional

The entity type, which in this case is "group".

descriptionstringOptional

The description of the payment group as provided in the request.

idstring · min: 1Optional

The unique identifier of the payment group.

lockedany ofOptional
booleanOptional

When locked, no new actions can be made.

or
string · enumOptional

When locked, no new actions can be made

Possible values:
walletstring · min: 1Optional

The Wallet ID linked to this group. All payments within this group will be associated with this wallet.

post/payments/groups
POST /payments/groups HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 99

{
  "name": "text",
  "description": "text",
  "wallet": "text",
  "user_tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}
200

Successful response

{
  "name": "text",
  "type": "text",
  "description": "text",
  "id": "text",
  "locked": true,
  "user_tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "wallet": "text"
}

Get Payment Groups List

get
/payments/groups

The Get Payment Groups List API is designed to fetch comprehensive information about all payment groups within an account. This API allows developers to retrieve detailed information about all payment groups associated with an organization’s account. It provides flexibility through filtering, sorting, and pagination, enabling efficient management and retrieval of group data.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
descriptionstring · min: 2Optional

Filter payment groups by their description (e.g., ?description=Cycle).

idany ofOptional

a list of group id's to filter by

stringOptional
or
string[]Optional
lockedany ofOptional

Filter payment groups by their locked status. Locked groups do not allow new payments (e.g., ?locked=true&locked=false).

stringOptional
or
boolean[]Optional
namestring · min: 2Optional

name of group to filter by (name)

skipintegerOptional

the number of items to skip in the result set

takeintegerOptional

the maximum number of items to return in the result set

Default: 50
walletany ofOptional

a list of wallet id's to filter by

stringOptional
or
string[]Optional
Responses
200

Successful response

application/json
get/payments/groups
GET /payments/groups HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

Successful response

{
  "items": [
    {
      "info": {
        "funding": {
          "next": "2026-01-01",
          "missing_funds": 1
        },
        "payments": {
          "total": 1,
          "pending": 1,
          "pending_approval": 1,
          "issues": 1,
          "completed": 1,
          "failed": 1,
          "routing": 1,
          "next": "2026-01-01",
          "amount": {
            "amount": 1,
            "currency": "text"
          }
        }
      },
      "name": "text",
      "type": "text",
      "description": "text",
      "id": "text",
      "locked": true,
      "user_tags": {},
      "wallet": {
        "name": "text",
        "type": "text",
        "id": "text",
        "currency": "text",
        "balance": 1,
        "owner": "text"
      }
    }
  ],
  "paging": {
    "skip": 1,
    "take": 1
  }
}

Delete Payment Group

delete
/payments/groups/{id}

The Delete Payment Group API is used to permanently remove a payment group from an account. This API enables developers to delete a payment group from an account. It is important to note that a payment group can only be deleted if it is empty, meaning it does not contain any executed payments. If there are pending payments within the group, the API provides an option to clear these before deletion.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired

The unique identifier of the payment group to be deleted.

Query parameters
clearbooleanRequired

a group can only be deleted if empty, if it has non executed payments setting the to true will remove all pending payments and then delete.

Responses
200

Successful response

application/json
delete/payments/groups/{id}
DELETE /payments/groups/{id}?clear=true HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

Successful response

{
  "group": {
    "id": "text",
    "result": true
  },
  "payments": [
    {
      "type": "text",
      "id": "text"
    }
  ]
}

Get Payment Group Details

get
/payments/groups/{id}

The Get Payment Group Details API is designed to provide detailed information about a specific payment group. This API allows developers to retrieve comprehensive details about a specific payment group by specifying the group ID. The information returned includes the group’s metadata, associated wallet information, payment details, and other relevant attributes that help in managing and auditing payment groups.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired

The unique identifier of the payment group whose details you want to retrieve.

Responses
200

Successful response

application/json
namestringOptional

The visual name of the payment group.

typestringOptional

The entity type, which is “group” for payment groups.

descriptionstringOptional

An extended description of the payment group.

idstringOptional

The unique identifier of the payment group.

lockedbooleanOptional

Indicates if the group is locked. When locked, no new payments can be added.

user_tagsobjectOptional

A set of key/value pairs assigned to the payment group for categorization.

get/payments/groups/{id}
GET /payments/groups/{id} HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

Successful response

{
  "info": {
    "funding": {
      "next": "2026-01-01",
      "missing_funds": 1
    },
    "payments": {
      "total": 1,
      "pending": 1,
      "pending_approval": 1,
      "issues": 1,
      "completed": 1,
      "failed": 1,
      "routing": 1,
      "next": "2026-01-01",
      "amount": {
        "amount": 1,
        "currency": "text"
      }
    }
  },
  "name": "text",
  "type": "text",
  "description": "text",
  "id": "text",
  "locked": true,
  "user_tags": {},
  "wallet": {
    "name": "text",
    "type": "text",
    "id": "text",
    "currency": "text",
    "balance": 1,
    "owner": "text"
  }
}

Update A Payment Group

put
/payments/groups/{id}

The Update A Payment Group API is used to change the details of an existing payment group. This API allows developers to modify an existing payment group by updating its name, description, and user tags. This is essential for maintaining accurate and up-to-date information about payment groups within the system.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired

The unique identifier of the payment group to be updated.

Body
namestringOptional

An updated name for the payment group.

descriptionstringOptional

An updated description for the payment group.

idstringRequired

The unique identifier of the payment group to be updated.

Responses
200

Successful response

application/json
namestring · min: 1Optional

The updated visual name of the payment group.

typestringOptional

The entity type, which is “group”.

descriptionstringOptional

The extended description of the payment group.

idstring · min: 1Optional

The unique identifier of the payment group.

lockedany ofOptional

Indicates whether the group is locked. A locked group cannot accept new payments.

booleanOptional
or
string · enumOptionalPossible values:
walletstring · min: 1Optional

The ID of the wallet associated with this group.

put/payments/groups/{id}
PUT /payments/groups/{id} HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 95

{
  "name": "text",
  "description": "text",
  "id": "text",
  "user_tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}
200

Successful response

{
  "name": "text",
  "type": "text",
  "description": "text",
  "id": "text",
  "locked": true,
  "user_tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "wallet": "text"
}

Lock Payment Group

patch
/payments/groups/{id}/lock

The Lock Payment Group API is used to secure a payment group by locking it, which prevents any further changes or additions of payments to the group. This API allows developers to lock a specific payment group, preventing any further payments from being added to the group. This is essential for finalizing a payment group, ensuring that no additional modifications can be made.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired

The unique identifier of the payment group to be locked.

Responses
200

Successful response

application/json
namestring · min: 1Optional

The visual name of the locked payment group.

typestringOptional

The entity type, which is “group”.

descriptionstringOptional

Extended description of the group.

idstring · min: 1Optional

The unique identifier of the payment group to be locked.

lockedany ofOptional
booleanOptional

Confirms whether the group has been successfully locked. The value will be true if the group is now locked.

or
string · enumOptional

When locked, no new actions can be made

Possible values:
user_tagsobjectOptional

A set of key/value pairs of tags set for the group.

walletstring · min: 1Optional

The ID of the wallet this group is associated with.

patch/payments/groups/{id}/lock
PATCH /payments/groups/{id}/lock HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

Successful response

{
  "name": "text",
  "type": "text",
  "description": "text",
  "id": "text",
  "locked": true,
  "user_tags": {},
  "wallet": "text"
}

UnLock Payment Group

delete
/payments/groups/{id}/lock

The Unlock Payment Group API is used to remove the locked status of a payment group. This API is designed to unlock a previously locked payment group, allowing additional payments to be added to the group. Unlocking a payment group is useful in situations where changes or additions are necessary after the group has been locked.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired

The unique identifier of the payment group to be unlocked.

Responses
200

Successful response

application/json
namestring · min: 1Optional

The visual name of the unlocked payment group.

typestringOptional
descriptionstringOptional

Extended description of the group.

idstring · min: 1Optional

The unique identifier of the unlocked payment group.

lockedany ofOptional

Indicates the locked status of the group. The value will be false if the group is now unlocked.

booleanOptional

When locked, no new actions can be made.

or
string · enumOptional

When locked, no new actions can be made.

Possible values:
user_tagsobjectOptional

A set of key/value pairs of tags set for the group.

walletstring · min: 1Optional

The ID of the wallet this group is associated with.

delete/payments/groups/{id}/lock
DELETE /payments/groups/{id}/lock HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

Successful response

{
  "name": "text",
  "type": "text",
  "description": "text",
  "id": "text",
  "locked": true,
  "user_tags": {},
  "wallet": "text"
}

Last updated