Token Charging

Merchant-initiated token charging for saved payment methods. This feature is not available by default - please contact your @tribute manager for details

List Shop Tokens

get

Returns a list of saved payment tokens for the authenticated shop. Requires tokenCharging to be enabled for the shop.

Authorizations

ApiKeyAuth

Api-KeystringRequired

API key for authentication.

Query parameters

customerIdstringOptional

Filter tokens by customer ID

Example: user_12345

orderUuidstring · uuidOptional

Filter tokens by the original order UUID

Example: 550e8400-e29b-41d4-a716-446655440000

activestring · enumOptional

Filter by active status (true to return only active tokens)

Example: truePossible values:

limitinteger · min: 1 · max: 100Optional

Maximum number of tokens to return (default 50, max 100)

Default: 50Example: 50

offsetintegerOptional

Number of tokens to skip for pagination

Default: 0Example: 0

Responses

200

Successful response

application/json

tokenstring · uuidRequired

Payment token UUID

Example: 550e8400-e29b-41d4-a716-446655440000

cardLast4stringRequired

Last 4 digits of the card number

Example: 1234

cardBrandstringRequired

Card brand (VISA, MASTERCARD, etc.)

Example: VISA

customerIdstringOptional

Merchant's customer reference (optional)

Example: user_12345

amountinteger · int64Required

Fixed charge amount in smallest currency units

Example: 100000

currencystring · enumRequired

Currency code (lowercase)

Example: rubPossible values:

activebooleanRequired

Whether the token is active and can be charged

Example: true

createdAtstring · date-timeRequired

Token creation timestamp in ISO 8601 format

Example: 2025-03-20T01:15:58Z

lastUsedAtstring · date-timeOptional

Last time the token was charged (optional)

Example: 2025-03-25T12:30:00Z

401

Unauthorized (invalid API key)

application/json

403

Token charging not enabled for this shop

application/json

404

Shop not found

application/json

get

/shop/tokens

HTTPcURLJavaScriptPython

GET /api/v1/shop/tokens HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

[
  {
    "token": "550e8400-e29b-41d4-a716-446655440000",
    "cardLast4": "1234",
    "cardBrand": "VISA",
    "customerId": "user_12345",
    "amount": 100000,
    "currency": "rub",
    "active": true,
    "createdAt": "2025-03-20T01:15:58Z",
    "lastUsedAt": "2025-03-25T12:30:00Z"
  }
]

Get Shop Token

get

Returns details of a specific saved payment token. Requires tokenCharging to be enabled for the shop.

Authorizations

ApiKeyAuth

Api-KeystringRequired

API key for authentication.

Path parameters

tokenstring · uuidRequired

Token UUID

Example: 550e8400-e29b-41d4-a716-446655440000

Responses

200

Successful response

application/json

tokenstring · uuidRequired

Payment token UUID

Example: 550e8400-e29b-41d4-a716-446655440000

cardLast4stringRequired

Last 4 digits of the card number

Example: 1234

cardBrandstringRequired

Card brand (VISA, MASTERCARD, etc.)

Example: VISA

customerIdstringOptional

Merchant's customer reference (optional)

Example: user_12345

amountinteger · int64Required

Fixed charge amount in smallest currency units

Example: 100000

currencystring · enumRequired

Currency code (lowercase)

Example: rubPossible values:

activebooleanRequired

Whether the token is active and can be charged

Example: true

createdAtstring · date-timeRequired

Token creation timestamp in ISO 8601 format

Example: 2025-03-20T01:15:58Z

lastUsedAtstring · date-timeOptional

Last time the token was charged (optional)

Example: 2025-03-25T12:30:00Z

401

Unauthorized (invalid API key)

application/json

403

Token charging not enabled for this shop

application/json

404

Token or shop not found

application/json

get

/shop/tokens/{token}

HTTPcURLJavaScriptPython

GET /api/v1/shop/tokens/{token} HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

{
  "token": "550e8400-e29b-41d4-a716-446655440000",
  "cardLast4": "1234",
  "cardBrand": "VISA",
  "customerId": "user_12345",
  "amount": 100000,
  "currency": "rub",
  "active": true,
  "createdAt": "2025-03-20T01:15:58Z",
  "lastUsedAt": "2025-03-25T12:30:00Z"
}

Deactivate Shop Token

delete

Deactivates a saved payment token, preventing it from being used for future charges. Requires tokenCharging to be enabled for the shop.

Authorizations

ApiKeyAuth

Api-KeystringRequired

API key for authentication.

Path parameters

tokenstring · uuidRequired

Token UUID

Example: 550e8400-e29b-41d4-a716-446655440000

Responses

200

Token deactivated successfully

application/json

successbooleanRequiredExample: true

messagestringRequiredExample: token deactivated

400

Bad request

application/json

401

Unauthorized (invalid API key)

application/json

403

Token charging not enabled for this shop

application/json

404

Token or shop not found

application/json

delete

/shop/tokens/{token}

HTTPcURLJavaScriptPython

DELETE /api/v1/shop/tokens/{token} HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "message": "token deactivated"
}

Create Shop Charge

post

Creates a new merchant-initiated charge against a saved payment token. The merchant specifies the charge amount in smallest currency units (cents/kopecks). Requires tokenCharging to be enabled for the shop.

Amount Limits (in smallest currency units):

• EUR: 100 - 300,000 (€1 - €3,000)

• RUB: 10,000 - 30,000,000 (₽100 - ₽300,000)

• USD: 100 - 300,000 ($1 - $3,000)

Rate Limiting:

• 1 minute cooldown between charges on the same token (returns 429 with remaining seconds)

• Only one pending charge per token at a time (returns 409)

Idempotency: Use the idempotencyKey parameter to safely retry requests. If a charge with the same idempotency key already exists, the existing charge will be returned.

Authorizations

ApiKeyAuth

Api-KeystringRequired

API key for authentication.

Body

application/json

tokenstring · uuidRequired

The payment token UUID to charge

Example: 550e8400-e29b-41d4-a716-446655440000

amountinteger · int64Required

Charge amount in smallest currency units (cents/kopecks)

Example: 100000

referencestring · max: 256Optional

Merchant reference for this charge (optional, max 256 chars)

Example: order-123

idempotencyKeystring · max: 64Optional

Unique key to prevent duplicate charges (optional, max 64 chars)

Example: charge-req-abc123

Responses

200

Charge created successfully

application/json

chargeUuidstring · uuidRequired

Charge UUID

Example: 550e8400-e29b-41d4-a716-446655440000

statusstring · enumRequired

Charge status

Example: processingPossible values:

referencestringOptional

Merchant reference (optional)

Example: order-123

amountinteger · int64Required

Charge amount in smallest currency units

Example: 100000

currencystring · enumRequired

Currency code (lowercase)

Example: rubPossible values:

tokenstring · uuidOptional

Payment token UUID

Example: 550e8400-e29b-41d4-a716-446655440000

errorCodestringOptional

Error code if charge failed (optional)

Example: payment_declined

errorMessagestringOptional

Error message if charge failed (optional)

Example: Card was declined by the issuer

createdAtstring · date-timeRequired

Charge creation timestamp in ISO 8601 format

Example: 2025-03-20T01:15:58Z

processedAtstring · date-timeOptional

Charge processing completion timestamp (optional)

Example: 2025-03-20T01:16:02Z

400

Bad request

application/json

401

Unauthorized (invalid API key)

application/json

403

Token charging not enabled for this shop

application/json

404

Token or shop not found

application/json

409

Conflict - charge already pending

application/json

429

Rate limit exceeded - must wait before charging again

application/json

502

Payment gateway error

application/json

post

/shop/charges

HTTPcURLJavaScriptPython

POST /api/v1/shop/charges HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 125

{
  "token": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 100000,
  "reference": "order-123",
  "idempotencyKey": "charge-req-abc123"
}

{
  "chargeUuid": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "reference": "order-123",
  "amount": 100000,
  "currency": "rub",
  "token": "550e8400-e29b-41d4-a716-446655440000",
  "errorCode": "payment_declined",
  "errorMessage": "Card was declined by the issuer",
  "createdAt": "2025-03-20T01:15:58Z",
  "processedAt": "2025-03-20T01:16:02Z"
}

Get Shop Charge

get

Returns the status and details of a specific charge. Requires tokenCharging to be enabled for the shop.

Authorizations

ApiKeyAuth

Api-KeystringRequired

API key for authentication.

Path parameters

chargeUuidstring · uuidRequired

Charge UUID

Example: 550e8400-e29b-41d4-a716-446655440000

Responses

200

Successful response

application/json

chargeUuidstring · uuidRequired

Charge UUID

Example: 550e8400-e29b-41d4-a716-446655440000

statusstring · enumRequired

Charge status

Example: processingPossible values:

referencestringOptional

Merchant reference (optional)

Example: order-123

amountinteger · int64Required

Charge amount in smallest currency units

Example: 100000

currencystring · enumRequired

Currency code (lowercase)

Example: rubPossible values:

tokenstring · uuidOptional

Payment token UUID

Example: 550e8400-e29b-41d4-a716-446655440000

errorCodestringOptional

Error code if charge failed (optional)

Example: payment_declined

errorMessagestringOptional

Error message if charge failed (optional)

Example: Card was declined by the issuer

createdAtstring · date-timeRequired

Charge creation timestamp in ISO 8601 format

Example: 2025-03-20T01:15:58Z

processedAtstring · date-timeOptional

Charge processing completion timestamp (optional)

Example: 2025-03-20T01:16:02Z

401

Unauthorized (invalid API key)

application/json

403

Token charging not enabled for this shop

application/json

404

Charge or shop not found

application/json

get

/shop/charges/{chargeUuid}

HTTPcURLJavaScriptPython

GET /api/v1/shop/charges/{chargeUuid} HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

{
  "chargeUuid": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "reference": "order-123",
  "amount": 100000,
  "currency": "rub",
  "token": "550e8400-e29b-41d4-a716-446655440000",
  "errorCode": "payment_declined",
  "errorMessage": "Card was declined by the issuer",
  "createdAt": "2025-03-20T01:15:58Z",
  "processedAt": "2025-03-20T01:16:02Z"
}