{ "components": { "schemas": { "PaymentTransactionResponse": { "properties": { "links": { "$ref": "#/components/schemas/TransactionResponseLinks" }, "pagination": { "$ref": "#/components/schemas/TransactionResponsePagination" }, "data": { "type": "array", "description": "List of all completed payment transactions sorted by creation date.", "items": { "$ref": "#/components/schemas/PaymentTransactionDto" } } }, "type": "object", "required": [ "links", "pagination", "data" ] }, "TransactionResponse": { "properties": { "links": { "$ref": "#/components/schemas/TransactionResponseLinks" }, "pagination": { "$ref": "#/components/schemas/TransactionResponsePagination" }, "data": { "type": "array", "description": "List of all transactions with all details.", "items": { "$ref": "#/components/schemas/TransactionDto" } } }, "type": "object", "required": [ "links", "pagination", "data" ] }, "CardTransactionsResponse": { "$ref": "#/components/schemas/TransactionResponse" }, "TravelTransactionResponse": { "properties": { "links": { "$ref": "#/components/schemas/TransactionResponseLinks" }, "pagination": { "$ref": "#/components/schemas/TransactionResponsePagination" }, "data": { "type": "array", "description": "List of all transactions with all details.", "items": { "$ref": "#/components/schemas/TravelTransactionDto" } } }, "type": "object", "required": [ "links", "pagination", "data" ] }, "PostCardTransactionsRequest": { "type": "object", "required": [ "source" ], "properties": { "source": { "type": "string", "enum": [ "cards", "travel" ], "description": "The source of transactions to retrieve.\n- `cards` — settled card transactions (company cards).\n- `travel` — completed transactions from virtual travel cards created via API.\n", "example": "cards" }, "cardIds": { "type": "array", "minItems": 1, "items": { "type": "string", "format": "uuid", "example": "c8ddf33f-6244-4218-af7e-7a6fe0b13528" }, "description": "Optional list of card UUIDs (v4) to filter transactions.\nMust contain at least one element when provided.\nWhen provided without dates, all transaction history is returned for those cards.\n" }, "startDate": { "type": "string", "format": "date", "description": "Start date (inclusive) for filtering transactions, in `yyyy-MM-dd` format.\nMust not be a future date. Must not be after `endDate` when both are set.\nDefaults to yesterday (D-1) when `cardIds` is not provided.\n", "example": "2025-01-01" }, "endDate": { "type": "string", "format": "date", "description": "End date (inclusive) for filtering transactions, in `yyyy-MM-dd` format.\nMust not be a future date.\nDefaults to yesterday (D-1) when `cardIds` is not provided.\n", "example": "2025-01-31" }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Number of transactions returned per page. Defaults to 20 when omitted.\nMaximum **50** when `source=cards`; maximum **100** when `source=travel`.\n", "example": 20 }, "pageCursor": { "type": "string", "description": "Opaque cursor for the next page, returned in `pagination.nextCursor` from a previous response.\nOmit on the first request.\n", "example": "MTI7eyJ0cmFuc2FjdGlvbklkIjoiODA4MTUxOSIsImNyZWF0ZWRBdCI6IjE3NDY1NTUzMDI1MTIifq" } } }, "BadRequestErrorDto": { "properties": { "errors": { "items": { "type": "object" }, "type": "array" }, "message": { "type": "string" }, "statusCode": { "type": "number" } }, "type": "object", "required": [ "message", "statusCode" ] }, "TravelCardBookingDetails": { "properties": { "itineraryId": { "maxLength": 60, "type": "string", "description": "The travel itinerary where the card is used.", "example": "ITIN-993235" }, "bookingReference": { "maxLength": 60, "type": "string", "description": "The booking reference where the card is used.", "example": "BREF-334234" }, "transactionId": { "maxLength": 60, "type": "string", "description": "The transaction id.", "example": "TRX-673829" }, "otherCustomField": { "type": "string", "description": "Other custom key-value field", "example": "custom-value" } }, "type": "object" }, "TravelCardDto": { "properties": { "metadata": { "$ref": "#/components/schemas/TravelCardBookingDetails", "type": "object", "description": "Card metadata. Can be used to store additional information about the card, e.g. type: travel. Keys must be strings up to 50 chars. Values must be strings up to 255 chars", "example": { "itineraryId": "ITIN-993235", "bookingReference": "BREF-334234", "key1": "value1", "key2": "value2" } }, "name": { "pattern": "^[a-zA-Z0-9\\s]+$", "type": "string", "maxLength": 60, "minLength": 1, "description": "The name of the card.", "example": "Travel Card" }, "restrictions": { "$ref": "#/components/schemas/CardRestrictions", "minLength": 1, "type": "string" }, "id": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" }, "createdAt": { "type": "string", "example": "2024-12-25 10:35:00" }, "updatedAt": { "type": "string", "example": "2024-12-25 10:35:00" } }, "type": "object", "required": [ "name", "restrictions", "id", "createdAt", "updatedAt" ] }, "CardsPageDto": { "properties": { "rows": { "items": { "$ref": "#/components/schemas/CardDto" }, "type": "array" }, "count": { "type": "number", "example": 100 } }, "type": "object", "required": [ "rows", "count" ] }, "CardCreateDto": { "properties": { "name": { "pattern": "^[a-zA-Z0-9\\s]+$", "type": "string", "maxLength": 60, "minLength": 1, "description": "Name given to the card.", "example": "Travel Card" }, "metadata": { "type": "object", "description": "Set of key-value pairs that you can attach to the card. Limitations: maximum of 10 key-value pairs, keys cannot exceed 50 characters, values cannot exceed 255 characters.", "example": { "reservation_code": "abc123", "passenger_name": "John Doe" } }, "expectedChargeDateUTC": { "type": "string", "format": "date", "description": "The date when the card is expected to be charged (UTC). Must not be a past date. Applicable to customers with a `cards:multiple:write` credential.", "example": "2025-02-20" }, "restrictions": { "$ref": "#/components/schemas/CardRestrictions", "minLength": 1, "type": "string" } }, "type": "object", "required": [ "name", "restrictions" ] }, "CardDetailsDto": { "properties": { "details": { "$ref": "#/components/schemas/CardDetails" }, "name": { "pattern": "^[a-zA-Z0-9\\s]+$", "type": "string", "maxLength": 60, "minLength": 1, "description": "Name given to the card.", "example": "Travel Card" }, "metadata": { "type": "object", "description": "Set of key-value pairs that you can attach to the card. Limitations: maximum of 10 key-value pairs, keys cannot exceed 50 characters, values cannot exceed 255 characters.", "example": { "reservation_code": "abc123", "passenger_name": "John Doe" } }, "expectedChargeDateUTC": { "type": "string", "format": "date", "description": "The date when the card is expected to be charged (UTC), if provided during card creation.", "example": "2025-02-20" }, "restrictions": { "$ref": "#/components/schemas/CardRestrictions", "minLength": 1, "type": "string" }, "id": { "type": "string", "description": "Unique identifier of a card.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "createdAt": { "type": "string", "description": "Card creation date and time in UTC.", "example": "2024-12-25 10:35:00" }, "updatedAt": { "type": "string", "description": "Card last update date and time in UTC.", "example": "2024-12-25 10:35:00" } }, "type": "object", "required": [ "details", "name", "restrictions", "id", "createdAt", "updatedAt" ] }, "CardUpdateDto": { "properties": { "name": { "pattern": "^[a-zA-Z0-9\\s]+$", "type": "string", "maxLength": 60, "description": "Name given to the card.", "example": "Travel Card" }, "metadata": { "type": "object", "description": "Set of key-value pairs that you can attach to the card. Limitations: maximum of 10 key-value pairs, keys cannot exceed 50 characters, values cannot exceed 255 characters.", "example": { "reservation_code": "abc123", "passenger_name": "John Doe" } }, "restrictions": { "$ref": "#/components/schemas/CardRestrictionsUpdateDto" } }, "type": "object" }, "CardDto": { "properties": { "id": { "type": "string", "description": "Unique identifier of a card.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "createdAt": { "type": "string", "description": "Card creation date and time in UTC.", "pattern": "\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d.\\d+Z?", "example": "2024-12-25 10:35:00" }, "updatedAt": { "type": "string", "description": "Card last update date and time in UTC.", "pattern": "\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d.\\d+Z?", "example": "2024-12-25 10:35:00" }, "name": { "pattern": "^[a-zA-Z0-9\\s]+$", "type": "string", "maxLength": 60, "minLength": 1, "description": "Name given to the card.", "example": "Travel Card" }, "metadata": { "type": "object", "description": "Set of key-value pairs that you can attach to the card. Limitations: maximum of 10 key-value pairs, keys cannot exceed 50 characters, values cannot exceed 255 characters.", "example": { "reservation_code": "abc123", "passenger_name": "John Doe" } }, "expectedChargeDateUTC": { "type": "string", "format": "date", "description": "The date when the card is expected to be charged (UTC), if provided during card creation.", "example": "2025-02-20" }, "restrictions": { "$ref": "#/components/schemas/CardRestrictions", "minLength": 1, "type": "string" } }, "type": "object", "required": [ "id", "createdAt", "updatedAt", "name", "restrictions" ] }, "BoletosPageDto": { "properties": { "rows": { "items": { "$ref": "#/components/schemas/BoletoDto" }, "type": "array" }, "count": { "type": "number", "example": 100 } }, "type": "object", "required": [ "rows", "count" ] }, "BoletoCreateDto": { "properties": { "amount": { "exclusiveMinimum": true, "type": "number", "minLength": 1, "description": "Payment amount (positive)", "example": 5000, "minimum": 0 }, "dueDate": { "minLength": 10, "maxLength": 10, "type": "string", "oneOf": [ { "format": "date", "type": "string" }, { "format": "date-time", "type": "string" } ], "description": "Due date (ISO 8601 format: YYYY-MM-DD)", "example": "2025-01-15" }, "memo": { "maxLength": 100, "type": "string", "minLength": 1, "description": "Description (max 100 chars)", "example": "Payment for services" }, "payerData": { "$ref": "#/components/schemas/PayerDataDto", "minLength": 1, "type": "string", "description": "Payer information." }, "metadata": { "type": "object", "description": "Additional custom key-value pairs", "example": { "internalReference": "INV-789", "key1": "value1", "key2": "value2" } }, "bolepixEnabled": { "type": "boolean", "description": "If true, generates a BolePix boleto with a Pix QR code.", "default": true }, "fine": { "$ref": "#/components/schemas/FineDto" }, "interest": { "$ref": "#/components/schemas/InterestDto" } }, "type": "object", "required": [ "amount", "dueDate", "memo", "payerData" ] }, "BoletoExtendDto": { "properties": { "newDueDate": { "minLength": 10, "maxLength": 10, "type": "string", "description": "The new due date (ISO 8601 format YYYY-MM-DD).", "example": "2026-09-15" } }, "type": "object", "required": [ "newDueDate" ] }, "BoletoDto": { "properties": { "id": { "minLength": 36, "maxLength": 36, "type": "string", "description": "Unique boleto identification key in uuid v4 format.", "example": "4c2fa514-a44d-40f2-8d57-c0caf1b9165a" }, "boletoStatus": { "enum": [ "accepted", "rejected", "payment_notice", "notary_office_payment_notice", "registered", "payment_blocked", "paid", "written_off" ], "type": "string", "minLength": 1, "description": "Boleto status.", "example": "registered" }, "amount": { "exclusiveMinimum": true, "type": "number", "minLength": 1, "description": "The boleto payment amount.", "example": 4000, "minimum": 0 }, "dueDate": { "minLength": 10, "maxLength": 10, "type": "string", "oneOf": [ { "format": "date", "type": "string" }, { "format": "date-time", "type": "string" } ], "description": "The due date (ISO 8601 format YYYY-MM-DD).", "example": "2024-07-12" }, "memo": { "maxLength": 320, "type": "string", "minLength": 1, "description": "Optional note for the payer, shown on the boleto.", "example": "Payment for marketing services" }, "barcode": { "type": "string", "minLength": 1, "description": "The barcode for the boleto.", "example": "32994978900005000000001546128483498231955341" }, "digitableLine": { "type": "string", "minLength": 1, "description": "The digitable line for the boleto.", "example": "32990001524612848349582319553408497890000500002" }, "payerData": { "$ref": "#/components/schemas/PayerDataDto", "minLength": 1, "type": "string", "description": "Payer information." }, "qrCodeImage": { "type": "string", "description": "QR code image in base64 format for BolePix payments.", "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAY..." }, "bolepixEnabled": { "type": "boolean", "description": "If true, generates a BolePix boleto with a Pix QR code.", "default": true }, "paymentDetails": { "$ref": "#/components/schemas/PaymentDetailsDto", "description": "Payment details." }, "fine": { "$ref": "#/components/schemas/FineDto" }, "interest": { "$ref": "#/components/schemas/InterestDto" }, "metadata": { "type": "object", "description": "Boleto metadata.", "example": { "key1": "value1" } }, "createdAt": { "oneOf": [ { "format": "date", "type": "string" }, { "format": "date-time", "type": "string" } ], "minLength": 1, "type": "string", "description": "Creation date (ISO 8601).", "example": "2024-06-23T09:15:32Z" }, "updatedAt": { "oneOf": [ { "format": "date", "type": "string" }, { "format": "date-time", "type": "string" } ], "description": "Updated at (ISO 8601).", "example": "2024-06-26T12:53:47Z" } }, "type": "object", "required": [ "id", "boletoStatus", "amount", "dueDate", "memo", "barcode", "digitableLine", "payerData", "createdAt" ] }, "MccCategoriesResponse": { "properties": { "rows": { "type": "array", "items": { "$ref": "#/components/schemas/MccCategoryDto" } }, "count": { "type": "number", "example": 100 } }, "type": "object" }, "ErrorDto": { "properties": { "message": { "type": "string" }, "statusCode": { "type": "number" } }, "type": "object", "required": [ "message", "statusCode" ] }, "WebhookSubscriptionDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Subscription identifier.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "url": { "type": "string", "description": "HTTPS URL where events will be delivered.", "example": "https://your-app.com/webhooks/jeeves" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "transaction.auth.approved", "transaction.auth.declined", "transaction.failed", "transaction.settled" ] }, "description": "List of subscribed event types." }, "developerEmail": { "type": "string", "description": "Comma-separated list of alert email addresses.", "example": "dev1@example.com,dev2@example.com" }, "description": { "type": "string", "description": "Human-readable label for this subscription.", "nullable": true, "example": "Production webhook for card transactions" }, "timeoutMs": { "type": "integer", "minimum": 1000, "maximum": 30000, "default": 10000, "description": "HTTP delivery timeout in ms.", "example": 10000 }, "status": { "type": "string", "enum": [ "active", "paused", "disabled" ], "description": "Subscription status.", "example": "active" }, "version": { "type": "string", "description": "Payload schema version.", "example": "v1" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 creation timestamp.", "example": "2026-04-15T10:35:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 last-updated timestamp.", "example": "2026-04-15T10:35:00Z" } }, "required": [ "id", "url", "eventTypes", "developerEmail", "status", "version", "createdAt", "updatedAt" ] }, "WebhookSubscriptionCreateDto": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "description": "HTTPS URL where events will be delivered. Max 2048 chars.", "example": "https://your-app.com/webhooks/jeeves" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "transaction.auth.approved", "transaction.auth.declined", "transaction.failed", "transaction.settled" ] }, "description": "At least one event type to subscribe to." }, "developerEmail": { "type": "string", "maxLength": 1024, "description": "Comma-separated list of emails (max 5) for alerts. Max 1024 chars.", "example": "dev1@example.com,dev2@example.com" }, "description": { "type": "string", "maxLength": 255, "description": "Human-readable label for this subscription. Max 255 chars.", "example": "Production webhook for card transactions" }, "timeoutMs": { "type": "integer", "minimum": 1000, "maximum": 30000, "default": 10000, "description": "HTTP delivery timeout in ms. Default 10000, min 1000, max 30000.", "example": 10000 } }, "required": [ "url", "eventTypes", "developerEmail" ] }, "WebhookSubscriptionUpdateDto": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "description": "New HTTPS delivery URL. Max 2048 chars.", "example": "https://your-app.com/webhooks/jeeves" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "transaction.auth.approved", "transaction.auth.declined", "transaction.failed", "transaction.settled" ] }, "description": "Replaces the full list of subscribed event types (min 1)." }, "developerEmail": { "type": "string", "maxLength": 1024, "description": "Comma-separated alert emails (max 5). Max 1024 chars.", "example": "dev1@example.com" }, "description": { "type": "string", "maxLength": 255, "description": "Human-readable label. Max 255 chars.", "example": "Production webhook for card transactions" }, "timeoutMs": { "type": "integer", "minimum": 1000, "maximum": 30000, "description": "Delivery timeout in ms (1000–30000).", "example": 10000 }, "status": { "type": "string", "enum": [ "active", "paused", "disabled" ], "description": "Use to re-enable after circuit breaker.", "example": "active" } } }, "WebhookSubscriptionCreateResponse": { "allOf": [ { "$ref": "#/components/schemas/WebhookSubscriptionDto" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "Signing secret (whsec_…). Only returned on creation — store immediately.", "example": "whsec_a1b2c3d4e5f6..." } }, "required": [ "secret" ] } ] }, "WebhookRotateSecretResponse": { "allOf": [ { "$ref": "#/components/schemas/WebhookSubscriptionDto" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "New plaintext HMAC signing secret (whsec_…). Store immediately.", "example": "whsec_a1b2c3d4e5f6..." }, "previousSecretExpiresAt": { "type": "string", "format": "date-time", "description": "When the old secret stops being valid for signature verification (24-hour grace window).", "example": "2026-04-16T10:35:00Z" } }, "required": [ "secret", "previousSecretExpiresAt" ] } ] }, "WebhookTestDeliveryResponse": { "type": "object", "properties": { "result": { "type": "string", "enum": [ "success", "failed" ], "description": "Test delivery result.", "example": "success" }, "httpStatusCode": { "type": "integer", "description": "HTTP status returned by your endpoint (if reachable).", "nullable": true, "example": 200 }, "latencyMs": { "type": "integer", "description": "Round-trip latency in ms.", "nullable": true, "example": 150 }, "errorMessage": { "type": "string", "description": "Present on failure — describes the error.", "nullable": true } }, "required": [ "result" ] }, "WebhookEventDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event identifier.", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "eventType": { "type": "string", "enum": [ "transaction.auth.approved", "transaction.auth.declined", "transaction.failed", "transaction.settled" ], "description": "Event type.", "example": "transaction.auth.approved" }, "eventVersion": { "type": "string", "description": "Payload schema version.", "example": "v1" }, "payload": { "type": "object", "description": "Event payload." }, "idempotencyKey": { "type": "string", "format": "uuid", "description": "Idempotency key for deduplication." }, "status": { "type": "string", "enum": [ "pending", "delivering", "delivered", "partially_delivered", "failed" ], "description": "Event delivery status.", "example": "delivered" }, "occurredAt": { "type": "string", "format": "date-time", "description": "When the event occurred.", "example": "2026-04-20T10:00:00Z" }, "deliveredAt": { "type": "string", "format": "date-time", "description": "When the event was delivered.", "nullable": true, "example": "2026-04-20T10:00:01Z" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 creation timestamp.", "example": "2026-04-20T10:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 last-updated timestamp.", "example": "2026-04-20T10:00:01Z" } }, "required": [ "id", "eventType", "eventVersion", "status", "occurredAt", "createdAt", "updatedAt" ] }, "WebhookEventListResponse": { "type": "object", "properties": { "count": { "type": "number", "description": "Total number of events.", "example": 100 }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventDto" } } }, "required": [ "count", "rows" ] }, "WebhookDeliveryDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Delivery identifier." }, "transactionEventId": { "type": "string", "format": "uuid", "description": "Parent event ID." }, "subscriptionId": { "type": "string", "format": "uuid", "description": "Target subscription ID." }, "status": { "type": "string", "enum": [ "pending", "queued", "success", "failed", "pending_retry", "exhausted" ], "description": "Delivery status.", "example": "success" }, "triggerType": { "type": "string", "enum": [ "automatic", "automatic_retry", "manual" ], "description": "How the delivery was triggered.", "example": "automatic" }, "httpStatusCode": { "type": "integer", "description": "HTTP status returned by your endpoint.", "nullable": true, "example": 200 }, "responseBody": { "type": "string", "description": "First 1 KB of your endpoint's response body.", "nullable": true }, "errorMessage": { "type": "string", "description": "Error description if delivery failed.", "nullable": true }, "errorType": { "type": "string", "enum": [ "internal", "external" ], "description": "Error origin.", "nullable": true }, "attemptNumber": { "type": "integer", "description": "Delivery attempt count (1-based).", "example": 1 }, "nextRetryAt": { "type": "string", "format": "date-time", "description": "When the next retry will fire (if scheduled).", "nullable": true }, "deliveredAt": { "type": "string", "format": "date-time", "description": "When delivery succeeded.", "nullable": true }, "latencyMs": { "type": "integer", "description": "Round-trip latency in ms.", "nullable": true, "example": 150 }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 creation timestamp." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 last-updated timestamp." } }, "required": [ "id", "transactionEventId", "subscriptionId", "status", "triggerType", "attemptNumber", "createdAt", "updatedAt" ] }, "WebhookDeliveryListResponse": { "type": "object", "properties": { "rows": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryDto" } } }, "required": [ "rows" ] }, "TransactionResponseLinks": { "properties": { "next": { "type": "string", "nullable": true, "description": "Link to the next page; `null` if there is no next page.\nFor deprecated GET transaction endpoints, this may contain a URL with query parameters.\nFor `POST /v1/cards/transactions`, this field is always `null` — use `pagination.nextCursor` in the next request body instead.\n", "example": "/v1/transactions?pageCursor=MTI7eyJ0cmFuc2FjdGlvbklkIjoiODA4MTUxOSIsImNyZWF0ZWRBdCI6IjE3NDY1NTUzMDI1MTIifq" } }, "type": "object", "required": [ "next" ] }, "TransactionResponsePagination": { "properties": { "pageSize": { "type": "number", "description": "Number of transactions returned by page.", "default": 20, "example": 5 }, "totalCount": { "type": "number", "description": "Total number of transactions for your call.", "example": 41 }, "nextCursor": { "type": "string", "nullable": true, "description": "The cursor pointing to the next page; null if there's no next page.", "example": "MTI7eyJ0cmFuc2FjdGlvbklkIjoiODA4MTUxOSIsImNyZWF0ZWRBdCI6IjE3NDY1NTUzMDI1MTIifq" }, "hasNext": { "type": "boolean", "description": "True if there's a next page; false otherwise.", "example": true } }, "type": "object", "required": [ "pageSize", "totalCount", "hasNext" ] }, "CardActiveDateRangeRestrictions": { "properties": { "startDate": { "pattern": "\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d.\\d+Z?", "type": "string", "description": "Date and time when the card is activated to do transactions.", "example": "2024-12-25 00:00:00", "nullable": true }, "endDate": { "pattern": "\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d.\\d+Z?", "type": "string", "description": "Date and time when the card is deactivated and can't do transactions anymore.", "example": "2024-12-31 23:59:59", "nullable": true } }, "type": "object" }, "MerchantCategoryControl": { "type": "object", "properties": { "mode": { "type": "string", "description": "The mode of the merchant category control. \"allow\" means only specified categories are allowed, \"block\" means specified categories are blocked.", "enum": [ "allow", "block" ] }, "categoryIds": { "type": "array", "description": "Array of merchant category IDs for which mcc control will be applied.", "items": { "type": "string", "description": "The merchant category id.", "example": "Accounting" } } }, "required": [ "mode", "categoryIds" ] }, "CardRestrictions": { "properties": { "spendLimit": { "minLength": 1, "type": "number", "exclusiveMinimum": true, "description": "Maximum total amount that can be spent with the card in local currency. Must be greater than 0.", "example": 1000, "minimum": 0 }, "activeDateRangeUTC": { "$ref": "#/components/schemas/CardActiveDateRangeRestrictions" }, "maxTransactionCount": { "maximum": 10, "type": "number", "minimum": 1, "description": "The maximum number of transactions that can be made with the card.", "example": 10 }, "merchantCategory": { "$ref": "#/components/schemas/MerchantCategoryControl" } }, "type": "object", "required": [ "spendLimit" ] }, "TravelTransactionDto": { "properties": { "transactionId": { "type": "string", "description": "Unique identifier of a transaction.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "transactionDate": { "type": "string", "pattern": "\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d.\\d+Z?", "description": "The date and time the transaction occurred, in UTC.", "example": "2025-01-29 16:22:51" }, "settlementDate": { "type": "string", "pattern": "\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d.\\d+Z?", "description": "The date and time the transaction was settled, in UTC.", "example": "2025-01-30 08:00:03" }, "statementClosingDate": { "type": "string", "pattern": "\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d.\\d+Z?", "description": "The date and time the statement was closed, in UTC.", "example": "2025-01-30 08:00:03" }, "statementDueDate": { "type": "string", "pattern": "\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d.\\d+Z?", "description": "The date and time the statement due date, in UTC.", "example": "2025-01-30 08:00:03" }, "cardLastFour": { "type": "string", "description": "The last 4 digits of the card number.", "example": "9876" }, "merchantName": { "type": "string", "description": "The name of the merchant.", "example": "Starbucks" }, "transactionAmount": { "type": "number", "description": "Transaction amount in account currency.", "example": 741.33 }, "transactionCurrency": { "type": "string", "description": "Currency code of the transaction amount (ISO 4217).", "example": "BRL" }, "localAmount": { "type": "number", "description": "Transaction amount in the currency of the transaction location.", "example": 127.59 }, "localCurrency": { "type": "string", "description": "Currency code of the local transaction amount (ISO 4217).", "example": "USD" }, "transactionType": { "type": "string", "description": "Debit for purchases and fees; credit for payments and refunds.", "enum": [ "debit", "credit" ], "example": "debit" }, "merchantCategoryCode": { "type": "string", "description": "Merchant Category Code (MCC) used by the merchant.", "example": "5814" }, "cardholderName": { "type": "string", "description": "The name of the cardholder.", "example": "John Doe" }, "cardName": { "type": "string", "description": "The name of the card.", "example": "Travel Card" }, "cardId": { "type": "string", "description": "The ID of the card.", "example": "c8ddf33f-6244-4218-af7e-7a6fe0b13528" }, "authorizationCode": { "type": "string", "description": "The authorization code of the transaction.", "example": "123456" }, "metadata": { "type": "object", "description": "The metadata of the transaction.", "example": { "reservation_code": "abc123", "passenger_name": "John Doe" } }, "restrictions": { "$ref": "#/components/schemas/CardRestrictions", "minLength": 1, "type": "string" } }, "type": "object", "required": [ "transactionId", "transactionDate", "merchantName", "transactionAmount", "transactionCurrency", "localAmount", "localCurrency", "transactionType", "merchantCategoryCode", "cardholderName", "cardName", "cardId", "authorizationCode", "metadata", "restrictions" ] }, "CardDetails": { "properties": { "cardNumber": { "type": "string", "description": "Card 16-digit number.", "example": "1234567890123456" }, "cardHolder": { "type": "string", "description": "Card holder name.", "example": "John Doe" }, "expiryDate": { "type": "string", "description": "Expiration date of the card.", "example": "12/27" }, "cvvCode": { "type": "string", "description": "3-digit code usually printed on the back of the card.", "example": "123" } }, "type": "object", "required": [ "cardNumber", "cardHolder", "expiryDate", "cvvCode" ] }, "TransactionDto": { "properties": { "id": { "type": "string", "description": "Unique identifier of a transaction.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productType": { "type": "string", "description": "It identifies if the card is on credit line or self funded.", "enum": [ "credit_line", "self_funded" ], "example": "credit_line" }, "company": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Company identification within Jeeves.", "example": "361c697b-8d82-11ec-a51a-0ea06e4de10b" }, "name": { "type": "string", "description": "Company name within Jeeves.", "example": "Acme Corporation" } } }, "user": { "type": "object", "required": [ "id", "name", "email" ], "properties": { "id": { "type": "string", "description": "User identifier within Jeeves.", "example": "d5d5c940-3c58-4ecc-b772-fe20e764ed70" }, "name": { "type": "string", "description": "User full name.", "example": "John Doe" }, "email": { "type": "string", "description": "User email address.", "example": "john.doe@acmecorp.com" } } }, "card": { "type": "object", "required": [ "id", "name", "type", "number" ], "properties": { "id": { "type": "string", "description": "Card identifier within Jeeves.", "example": "c8ddf33f-6244-4218-af7e-7a6fe0b13528" }, "name": { "type": "string", "description": "Card label defined by the user.", "example": "Travel Card" }, "type": { "type": "string", "description": "Card type.", "enum": [ "Physical", "Virtual" ], "example": "Physical" }, "number": { "type": "string", "description": "Last 4 digits of the card number.", "example": "9876" } } }, "merchant": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 150, "description": "Name of the merchant where the transaction happened.", "example": "STARBUCKS SAO PAULO BRA" }, "mcc": { "type": "string", "description": "Merchant Category Code (MCC) used by the merchant.", "example": "5814" }, "mccDescription": { "type": "string", "description": "MCC description provided by the network.", "example": "Fast Food Restaurants" } } }, "transactionType": { "type": "string", "description": "Debit for purchases and fees; credit for payments and refunds.", "enum": [ "debit", "credit" ], "example": "debit" }, "transactionDate": { "type": "string", "pattern": "\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d.\\d+Z?", "description": "The date and time the transaction occurred, in UTC.", "example": "2025-01-29 16:22:51" }, "settlementDate": { "type": "string", "pattern": "\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d.\\d+Z?", "description": "The date and time the transaction was settled, in UTC.", "example": "2025-01-30 08:00:03" }, "transactionAmount": { "type": "number", "description": "Transaction amount in account currency.", "example": 741.33 }, "transactionCurrency": { "type": "string", "description": "Currency code of the transaction amount (ISO 4217).", "example": "BRL" }, "localTransactionAmount": { "type": "number", "description": "Transaction amount in the currency of the transaction location.", "example": 127.59 }, "localTransactionCurrency": { "type": "string", "description": "Currency code of the local transaction amount (ISO 4217).", "example": "USD" } }, "type": "object", "required": [ "id", "productType", "company", "user", "card", "merchant", "transactionType", "transactionDate", "settlementDate", "transactionAmount", "transactionCurrency", "localTransactionAmount", "localTransactionCurrency" ] }, "CardRestrictionsUpdateDto": { "properties": { "spendLimit": { "type": "string", "exclusiveMinimum": true, "minLength": 1, "description": "The maximum total amount that can be spent with the card. Must be greater than 0.", "example": 1000, "minimum": 0 }, "activeDateRangeUTC": { "$ref": "#/components/schemas/CardActiveDateRangeRestrictions" }, "maxTransactionCount": { "maximum": 10, "type": "number", "minimum": 1, "description": "The maximum number of transactions that can be made with the card.", "example": 10 }, "merchantCategory": { "$ref": "#/components/schemas/MerchantCategoryControl" } }, "type": "object" }, "MccCategoryDto": { "properties": { "merchantCategoryId": { "type": "string", "description": "The merchant category id.", "example": "Lodging & Accommodations" }, "merchantCategoryName": { "type": "string", "enum": [ "Accounting", "Airfare", "Conference & Events", "Contractor Services", "Equipment Expense", "Freight & Shipping", "Insurance", "Legal Expense", "Lodging & Accommodations", "Marketing", "Meals & Entertainment", "Membership Dues & Subscriptions", "Office Expense", "Other Expense", "Other Miscellaneous", "Postage & Shipping", "Rent", "Retail Purchases", "Software Expense", "Taxes and Licensing", "Transportation Services", "Utility Services" ], "description": "The merchant category name.", "example": "Lodging" }, "merchantCategoryCodes": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "The merchant category code.", "example": "5812" }, "name": { "type": "string", "description": "The merchant category code name.", "example": "Eating Places and Restaurants" } } } } } }, "PaymentTransactionDto": { "properties": { "id": { "type": "string", "description": "Unique identifier of a transaction.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productType": { "type": "string", "description": "It identifies if the card is on credit line or self funded.", "enum": [ "credit_line", "self_funded" ], "example": "credit_line" }, "company": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Company identification within Jeeves.", "example": "361c697b-8d82-11ec-a51a-0ea06e4de10b" }, "name": { "type": "string", "description": "Company name within Jeeves.", "example": "Acme Corporation" } } }, "user": { "type": "object", "required": [ "id", "name", "email" ], "properties": { "id": { "type": "string", "description": "User identifier within Jeeves.", "example": "d5d5c940-3c58-4ecc-b772-fe20e764ed70" }, "name": { "type": "string", "description": "User full name.", "example": "John Doe" }, "email": { "type": "string", "description": "User email address.", "example": "john.doe@acmecorp.com" } } }, "vendor": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Vendor identifier within Jeeves.", "example": "c8ddf33f-6244-4218-af7e-7a6fe0b13528" }, "name": { "type": "string", "description": "Vendor name defined by the user.", "example": "Omni Corporation" } } }, "transactionType": { "type": "string", "description": "Debit for purchases and fees; credit for payments and refunds.", "enum": [ "debit", "credit" ], "example": "debit" }, "transactionDate": { "type": "string", "pattern": "\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d.\\d+Z?", "description": "The date and time the transaction occurred, in UTC.", "example": "2025-01-29 16:22:51" }, "settlementDate": { "type": "string", "pattern": "\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d.\\d+Z?", "description": "The date and time the transaction was settled, in UTC.", "example": "2025-01-30 08:00:03" }, "transactionAmount": { "type": "number", "description": "Transaction amount in account currency.", "example": 741.33 }, "transactionCurrency": { "type": "string", "description": "Currency code of the transaction amount (ISO 4217).", "example": "BRL" }, "localTransactionAmount": { "type": "number", "description": "Transaction amount in the currency of the transaction location.", "example": 127.59 }, "localTransactionCurrency": { "type": "string", "description": "Currency code of the local transaction amount (ISO 4217).", "example": "USD" }, "paymentPurpose": { "type": "string", "description": "Purpose of the payment, if any.", "example": "Utility payment to Electric Company" } }, "type": "object", "required": [ "id", "productType", "company", "user", "vendor", "transactionType", "transactionDate", "settlementDate", "transactionAmount", "transactionCurrency", "localTransactionAmount", "localTransactionCurrency" ] }, "PayerPhoneDto": { "properties": { "countryCode": { "maxLength": 3, "type": "string", "minLength": 1, "description": "The payer phone international dial code", "example": "055" }, "areaCode": { "maxLength": 2, "type": "string", "minLength": 1, "description": "The payer phone area code", "example": "11" }, "number": { "maxLength": 9, "type": "string", "minLength": 1, "description": "The payer phone number", "example": "987654321" } }, "type": "object", "required": [ "countryCode", "areaCode", "number" ] }, "PayerAddressDto": { "properties": { "street": { "maxLength": 500, "type": "string", "minLength": 1, "description": "The payer address street name.", "example": "101 High St." }, "number": { "maxLength": 6, "type": "string", "minLength": 1, "description": "The payer address number.", "example": "202" }, "complement": { "maxLength": 500, "type": "string", "description": "The payer address complement.", "example": "Building A" }, "neighborhood": { "maxLength": 100, "type": "string", "minLength": 1, "description": "The payer address neighborhood.", "example": "Tech Park" }, "postalCode": { "minLength": 8, "maxLength": 8, "type": "string", "description": "The payer address postal code (CEP).", "example": "01001000" }, "city": { "maxLength": 100, "type": "string", "minLength": 1, "description": "The payer address city.", "example": "São Paulo" }, "state": { "enum": [ "AC", "AL", "AM", "AP", "BA", "CE", "DF", "ES", "GO", "MA", "MG", "MS", "MT", "PA", "PB", "PE", "PI", "PR", "RJ", "RN", "RO", "RR", "RS", "SC", "SE", "SP", "TO" ], "type": "string", "minLength": 1, "description": "The payer address state.", "example": "SP" } }, "type": "object", "required": [ "street", "number", "neighborhood", "postalCode", "city", "state" ] }, "PayerDataDto": { "properties": { "name": { "maxLength": 100, "type": "string", "minLength": 1, "description": "The payer name.", "example": "Global Tech" }, "personType": { "enum": [ "natural", "legal" ], "type": "string", "minLength": 1, "description": "The type of person.", "example": "legal" }, "documentNumber": { "type": "string", "minLength": 11, "maxLength": 14, "description": "The payer document number (CPF for natural person - 11 digits, CNPJ for legal person - 14 digits).", "example": "12345678000195" }, "email": { "maxLength": 320, "type": "string", "format": "email", "minLength": 1, "description": "The payer email address", "example": "finance@globaltech.com" }, "phone": { "$ref": "#/components/schemas/PayerPhoneDto", "minLength": 1, "type": "string", "description": "The payer phone information." }, "address": { "$ref": "#/components/schemas/PayerAddressDto", "minLength": 1, "type": "string", "description": "The payer address information." } }, "type": "object", "required": [ "name", "personType", "documentNumber", "email", "phone", "address" ] }, "PaymentDetailsDto": { "properties": { "paidAmount": { "exclusiveMinimum": true, "type": "string", "minLength": 1, "description": "The paid amount.", "example": 5000, "minimum": 0 }, "method": { "enum": [ "cash", "account_debit", "credit_card", "check", "pix", "manual", "other" ], "type": "string", "minLength": 1, "description": "The payment method.", "example": "account_debit" }, "origin": { "enum": [ "phisical_cashier", "internet", "corban", "call_center", "eletronic_file", "dda", "digital_correspondent", "qr_code", "barcode", "manual", "cup" ], "type": "string", "minLength": 1, "description": "The payment origin.", "example": "qr_code" }, "creditDate": { "oneOf": [ { "format": "date", "type": "string" }, { "format": "date-time", "type": "string" } ], "minLength": 1, "type": "string", "description": "The payment credit date (ISO 8601 format YYYY-MM-DD).", "example": "2025-01-15" } }, "type": "object", "required": [ "paidAmount", "method", "origin", "creditDate" ] }, "FineDto": { "description": "Fine to be applied.", "properties": { "type": { "type": "string", "description": "Type of fine to be applied.", "enum": [ "absolute", "percentage" ], "example": "absolute" }, "amount": { "type": "number", "description": "Absolute fine amount.", "example": 100 }, "percentage": { "type": "number", "description": "Percentage-based fine on the boleto amount.", "example": 10 }, "daysAfterDue": { "type": "number", "description": "Days after due when fine is applied (if absolute) or starts accruing (if percentage).", "example": 10 } }, "type": "object", "required": [ "type", "daysAfterDue" ] }, "InterestDto": { "description": "Interest to be applied.", "properties": { "type": { "type": "string", "description": "Type of interest to be applied.", "enum": [ "calendar_days_daily_amount", "workdays_daily_amount", "calendar_days_monthly_percentage" ], "example": "calendar_days_daily_amount" }, "dailyAmount": { "type": "number", "description": "Interest amount to be charged per working or calendar day.", "example": 100 }, "monthlyPercentage": { "type": "number", "description": "Percentage-based interest on the boleto amount.", "example": 10 }, "daysAfterDue": { "type": "number", "description": "Days after due when interest starts accruing.", "example": 10 } }, "type": "object", "required": [ "type", "daysAfterDue" ] } }, "responses": { "BadRequest": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorDto" } } } }, "Unauthorized": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDto" } } } }, "Forbidden": { "description": "Forbidden request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDto" } } } }, "NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDto" } } } }, "InternalServerError": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDto" } } } } }, "securitySchemes": { "OAuth2ClientCredentials": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "http://localhost:4000/oauth/token", "scopes": { "cards:read": "Read cards.", "cards:write": "Create, Update or Delete Jeeves Virtual cards", "transactions:read": "Read transactions for reconciliation.", "transactions:multiple:read": "Read transactions from multiple organizational entities of the same parent company using a single API credential.", "boletos:read": "Read boletos.", "boletos:write": "Create/Cancel/Extend boletos." } } } } } }, "info": { "title": "Jeeves Public API", "version": "1.0.0", "description": "## Introduction\n\nThe Jeeves API is built around **REST** principles. Our API accepts **JSON-encoded** request bodies, returns **JSON-encoded** responses, and uses standard **HTTP** response codes.\n\n## Authentication\n\nThe Jeeves API uses **mTLS** and **OAuth 2.0** to authenticate requests. You can request your mTLS certificate and OAuth 2.0 credentials in both sandbox and production environments by reaching out to our support team.\n\n**All API requests will only work over HTTPS.** Calls made over plain HTTP will fail. API requests without authentication will also fail.\n\n## Errors\n\nThe Jeeves API uses standard **HTTP** response codes to indicate the success or failure of an API request. In general: codes in the **2XX** range indicate success; codes in the **4XX** range indicate an error in the information provided; codes in the **5XX** range indicate an internal error with Jeeves application/server.\n\nCurrently, the Jeeves API has the following HTTP responses:\n\n| Code | Response | Description |\n|:-----|:---------|:------------|\n| 200 | Ok | Object was returned as expected. |\n| 201 | Ok | Object was created as expected. |\n| 204 | Ok | No return, but request was processed as expected. |\n| 400 | Bad request | At least one argument is wrong or missing. |\n| 401 | Unauthorized | No valid API token provided. |\n| 403 | Forbidden | The API token doesn't have permission to perform the request. |\n| 404 | Not found | The requested resource doesn't exist. |\n| 500 | Server error | An internal error at Jeeves. |\n" }, "tags": [ { "name": "Boletos", "description": "The Boleto API supports the full boleto lifecycle, enabling clients to create, retrieve, extend, and cancel boletos via secure integration. It also supports **Bolepix**, which adds a Pix QR code to the boleto for instant settlement through Pix rails. For boletos paid via barc*o*de or *digitable line*, the API provides an **early payment notice** before final settlement - offering visibility of the payment up to one day in advance, with guaranteed settlement. For boletos paid via Pix (via Bolepix), the boleto is marked as paid directly, as settlement is immediate." }, { "name": "Cards", "description": "The Card API supports the full card lifecycle, enabling clients to create, retrieve, and update cards via secure integration. Use `POST /v1/cards/transactions` with the `source` field to query card or travel transactions in a single endpoint." }, { "name": "Transactions", "description": "The Transactions API enables clients to retrieve card and payment transactions via secure integration. Supports filtering by date range and pagination for efficient data retrieval." }, { "name": "Travel", "description": "The Travel API enables clients to retrieve transactions from virtual travel cards and update booking details via secure integration." }, { "name": "Webhooks", "description": "The Webhooks API provides access to webhook subscription management and event tracking, enabling you to receive real-time HTTP notifications the moment a card transaction is approved, declined, settled, or fails." } ], "openapi": "3.0.0", "paths": { "/v1/travel/transactions": { "get": { "deprecated": true, "operationId": "TravelController.getTransactions", "parameters": [ { "in": "query", "name": "pageCursor", "schema": { "type": "string", "description": "The cursor of the next page of transactions (returned in the \"nextCursor\" property in the response).", "nullable": true, "default": null } }, { "in": "query", "name": "pageSize", "schema": { "maximum": 100, "type": "number", "minimum": 1, "description": "The page size.", "default": 100, "example": 100 } }, { "in": "query", "name": "startDate", "schema": { "oneOf": [ { "format": "date", "type": "string" }, { "format": "date-time", "type": "string" } ], "description": "The start date of the transaction.", "example": "2025-01-01", "default": "D-1 (yesterday)", "format": "yyyy-MM-dd" } }, { "in": "query", "name": "endDate", "schema": { "oneOf": [ { "format": "date", "type": "string" }, { "format": "date-time", "type": "string" } ], "description": "The end date of the transaction.", "example": "2025-01-01", "default": "D-1 (yesterday)", "format": "yyyy-MM-dd" } }, { "required": false, "name": "Accept-Language", "example": "en-US", "description": "Language code for localization.", "schema": { "type": "string", "enum": [ "en-US", "es-MX", "pt-BR" ], "default": "en-US" }, "in": "header" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelTransactionResponse" } } }, "description": "Paginated list of completed transactions done from the virtual cards created via API." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "Get transactions", "tags": [ "Travel" ], "security": [ { "OAuth2ClientCredentials": [ "transactions:read" ] } ], "description": "**Deprecated.** Use [`POST /v1/cards/transactions`](#tag/Cards/operation/CardsController.postCardTransactions) with `\"source\": \"travel\"` instead.\n\nGet completed transactions from the virtual cards created via API for reconciliation.\n" } }, "/v1/travel/cards/{id}/booking": { "patch": { "operationId": "TravelController.updateBookingDetails", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "[^\\/#\\?]+?", "type": "string" } }, { "required": false, "name": "Accept-Language", "example": "en-US", "description": "Language code for localization.", "schema": { "type": "string", "enum": [ "en-US", "es-MX", "pt-BR" ], "default": "en-US" }, "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelCardBookingDetails" } } }, "description": "TravelCardBookingDetails", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelCardDto" } } }, "description": "Travel card details." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "Update booking details", "tags": [ "Travel" ], "security": [ { "OAuth2ClientCredentials": [ "cards:write" ] } ] } }, "/v1/webhooks/subscriptions": { "post": { "operationId": "WebhooksController.createSubscription", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionCreateDto" } } }, "description": "WebhookSubscriptionCreateDto", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionCreateResponse" } } }, "description": "Webhook subscription created. The signing secret is returned once — store it immediately." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Company has reached the 10-subscription limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDto" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "Create subscription", "description": "Creates a new webhook subscription. Returns the signing secret in plaintext once — store it immediately, it is not shown again.", "tags": [ "Webhooks" ], "security": [ { "OAuth2ClientCredentials": [ "webhooks:write" ] } ] }, "get": { "operationId": "WebhooksController.listSubscriptions", "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscriptionDto" } } } }, "description": "List of all webhook subscriptions for the credential owner's company. The secret field is masked." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "List subscriptions", "description": "Returns all webhook subscriptions for the credential owner's company.", "tags": [ "Webhooks" ], "security": [ { "OAuth2ClientCredentials": [ "webhooks:read" ] } ] } }, "/v1/webhooks/subscriptions/{id}": { "get": { "operationId": "WebhooksController.getSubscription", "parameters": [ { "in": "path", "name": "id", "description": "Subscription identifier (UUID).", "required": true, "schema": { "pattern": "[^\\/#\\?]+?", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionDto" } } }, "description": "Webhook subscription details. The secret field is masked." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "Get subscription", "description": "Returns the details of a single webhook subscription.", "tags": [ "Webhooks" ], "security": [ { "OAuth2ClientCredentials": [ "webhooks:read" ] } ] }, "patch": { "operationId": "WebhooksController.updateSubscription", "parameters": [ { "in": "path", "name": "id", "description": "Subscription identifier (UUID).", "required": true, "schema": { "pattern": "[^\\/#\\?]+?", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionUpdateDto" } } }, "description": "WebhookSubscriptionUpdateDto", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionDto" } } }, "description": "Updated webhook subscription details." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "Update subscription", "description": "Updates a webhook subscription. Only fields you include are changed.", "tags": [ "Webhooks" ], "security": [ { "OAuth2ClientCredentials": [ "webhooks:write" ] } ] }, "delete": { "operationId": "WebhooksController.deleteSubscription", "parameters": [ { "in": "path", "name": "id", "description": "Subscription identifier (UUID).", "required": true, "schema": { "pattern": "[^\\/#\\?]+?", "type": "string" } } ], "responses": { "204": { "content": { "application/json": {} }, "description": "Subscription deleted." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "Delete subscription", "description": "Soft-deletes a webhook subscription. No further events will be delivered to this endpoint.", "tags": [ "Webhooks" ], "security": [ { "OAuth2ClientCredentials": [ "webhooks:write" ] } ] } }, "/v1/webhooks/subscriptions/{id}/rotate-secret": { "post": { "operationId": "WebhooksController.rotateSecret", "parameters": [ { "in": "path", "name": "id", "description": "Subscription identifier (UUID).", "required": true, "schema": { "pattern": "[^\\/#\\?]+?", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRotateSecretResponse" } } }, "description": "New signing secret issued. The previous secret remains valid for 24 hours." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "Rotate secret", "description": "Issues a new signing secret. The previous secret remains valid for 24 hours for a zero-downtime rollover.", "tags": [ "Webhooks" ], "security": [ { "OAuth2ClientCredentials": [ "webhooks:write" ] } ] } }, "/v1/webhooks/subscriptions/{id}/test": { "post": { "operationId": "WebhooksController.testSubscription", "parameters": [ { "in": "path", "name": "id", "description": "Subscription identifier (UUID).", "required": true, "schema": { "pattern": "[^\\/#\\?]+?", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestDeliveryResponse" } } }, "description": "Test delivery result with HTTP status and latency from your endpoint." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "Send test delivery", "description": "Posts a signed sample payload to your endpoint and returns the HTTP response inline. Not recorded in events or deliveries.", "tags": [ "Webhooks" ], "security": [ { "OAuth2ClientCredentials": [ "webhooks:write" ] } ] } }, "/v1/webhooks/events": { "get": { "operationId": "WebhooksController.listEvents", "parameters": [ { "in": "query", "name": "page", "required": false, "schema": { "type": "number", "minimum": 1, "default": 1 }, "description": "Page number to retrieve.", "example": 1 }, { "in": "query", "name": "pageSize", "required": false, "schema": { "type": "number", "minimum": 1, "maximum": 500, "default": 20 }, "description": "Number of events returned per page.", "example": 20 }, { "in": "query", "name": "eventType", "required": false, "schema": { "type": "string", "enum": [ "transaction.auth.approved", "transaction.auth.declined", "transaction.failed", "transaction.settled" ] }, "description": "Filter by event type." }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "enum": [ "pending", "delivering", "delivered", "partially_delivered", "failed" ] }, "description": "Filter by delivery status." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventListResponse" } } }, "description": "Paginated list of webhook events." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "List events", "description": "Returns a paginated list of webhook events, filterable by type and status.", "tags": [ "Webhooks" ], "security": [ { "OAuth2ClientCredentials": [ "webhooks:read" ] } ] } }, "/v1/webhooks/events/{id}": { "get": { "operationId": "WebhooksController.getEvent", "parameters": [ { "in": "path", "name": "id", "description": "Event identifier (UUID).", "required": true, "schema": { "pattern": "[^\\/#\\?]+?", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventDto" } } }, "description": "Event details with the latest delivery outcome per subscription." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "Get event", "description": "Returns event details with the latest delivery outcome per subscription.", "tags": [ "Webhooks" ], "security": [ { "OAuth2ClientCredentials": [ "webhooks:read" ] } ] } }, "/v1/webhooks/events/{id}/deliveries": { "get": { "operationId": "WebhooksController.listDeliveries", "parameters": [ { "in": "path", "name": "id", "description": "Event identifier (UUID).", "required": true, "schema": { "pattern": "[^\\/#\\?]+?", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryListResponse" } } }, "description": "List of delivery attempts for the given event." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "List deliveries", "description": "Lists the latest delivery attempt per subscription for a given event.", "tags": [ "Webhooks" ], "security": [ { "OAuth2ClientCredentials": [ "webhooks:read" ] } ] } }, "/v1/webhooks/events/{id}/retry": { "post": { "operationId": "WebhooksController.retryEvent", "parameters": [ { "in": "path", "name": "id", "description": "Event identifier (UUID).", "required": true, "schema": { "pattern": "[^\\/#\\?]+?", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryListResponse" } } }, "description": "Array of newly-created delivery rows triggered by this retry." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "An in-flight delivery exists for this event — wait for it to settle before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDto" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "Retry event", "description": "Resends this event to all active subscriptions. Skips disabled subscriptions. Fails if any delivery is still in progress. Manual retries are single-shot.", "tags": [ "Webhooks" ], "security": [ { "OAuth2ClientCredentials": [ "webhooks:write" ] } ] } }, "/v1/cards": { "get": { "operationId": "CardsController.getCards", "parameters": [ { "in": "query", "name": "page", "schema": { "minimum": 1, "type": "number", "description": "Page number to retrieve.", "default": 1, "example": 1 } }, { "in": "query", "name": "pageSize", "schema": { "maximum": 500, "type": "number", "minimum": 1, "description": "Number of items returned per page.", "default": 20, "example": 20 } }, { "required": false, "name": "Accept-Language", "example": "en-US", "description": "Language code used for localization.", "schema": { "type": "string", "enum": [ "en-US", "es-MX", "pt-BR" ], "default": "en-US" }, "in": "header" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardsPageDto" } } }, "description": "List of all cards with details." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "List all cards", "description": "You can see a list of cards belonging to the owner of the client credentials.", "tags": [ "Cards" ], "security": [ { "OAuth2ClientCredentials": [ "cards:read" ] } ] }, "post": { "operationId": "CardsController.createCard", "parameters": [ { "required": false, "name": "Accept-Language", "example": "en-US", "description": "Language code for localization.", "schema": { "type": "string", "enum": [ "en-US", "es-MX", "pt-BR" ], "default": "en-US" }, "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardCreateDto" } } }, "description": "CardCreateDto", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardDetailsDto" } } }, "description": "Card details." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "Create a card", "description": "You can create a new credit card assigned to the owner of the client credentials.", "tags": [ "Cards" ], "security": [ { "OAuth2ClientCredentials": [ "cards:write" ] } ] } }, "/v1/cards/transactions": { "post": { "operationId": "CardsController.postCardTransactions", "summary": "Retrieve card or travel transactions", "description": "Retrieve settled card transactions or completed travel card transactions through a single endpoint. The `source` field selects the backend and determines the response shape.\n\n**Response shape by source**\n\n| `source` | Response schema | Description |\n|:---------|:----------------|:------------|\n| `cards` | `TransactionResponse` | Settled card transactions for your company |\n| `travel` | `TravelTransactionResponse` | Completed transactions from virtual travel cards |\n\nBoth responses include a `pagination` object with `pageSize`, `totalCount`, `nextCursor`, and `hasNext`.\n\n**Pagination**\n\nBecause this is a POST endpoint, `links.next` is always `null` — the request body cannot be encoded in a URL. To page forward, send a new request with the same filters and set `pageCursor` to the value from `pagination.nextCursor`. Repeat until `pagination.hasNext` is `false`.\n\n**Default date window**\n\n- When `cardIds` is **not** provided, `startDate` and `endDate` both default to **yesterday** (D-1, `yyyy-MM-dd`).\n- When `cardIds` **is** provided, no default dates are applied — **all transaction history** is returned unless you set `startDate` and/or `endDate` explicitly.\n\n**Migration**\n\nThis endpoint replaces [`GET /v1/transactions`](#tag/Transactions/operation/TransactionsController.getTransactions) (use `\"source\": \"cards\"`) and [`GET /v1/travel/transactions`](#tag/Travel/operation/TravelController.getTransactions) (use `\"source\": \"travel\"`).\n", "tags": [ "Cards" ], "security": [ { "OAuth2ClientCredentials": [ "transactions:read", "transactions:multiple:read" ] } ], "parameters": [ { "required": false, "name": "Accept-Language", "example": "en-US", "description": "Language code used for localization.", "schema": { "type": "string", "enum": [ "en-US", "es-MX", "pt-BR" ], "default": "en-US" }, "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostCardTransactionsRequest" }, "examples": { "basicCards": { "summary": "Basic call with source=cards", "description": "Fetch card transactions for a specific date range.", "value": { "source": "cards", "startDate": "2025-01-01", "endDate": "2025-01-31" } }, "filterByCardIds": { "summary": "Filter by specific cards", "description": "Returns all history for the given cards (no date defaults applied).", "value": { "source": "cards", "cardIds": [ "c8ddf33f-6244-4218-af7e-7a6fe0b13528", "d5d5c940-3c58-4ecc-b772-fe20e764ed70" ] } }, "paginateWithCursor": { "summary": "Paginate through results", "description": "Pass `pagination.nextCursor` from the previous response as `pageCursor`.", "value": { "source": "cards", "startDate": "2025-01-01", "endDate": "2025-01-31", "pageSize": 25, "pageCursor": "MTI7eyJ0cmFuc2FjdGlvbklkIjoiODA4MTUxOSIsImNyZWF0ZWRBdCI6IjE3NDY1NTUzMDI1MTIifq" } }, "basicTravel": { "summary": "Basic call with source=travel", "description": "Fetch travel card transactions for a specific date range.", "value": { "source": "travel", "startDate": "2025-01-01", "endDate": "2025-01-31" } } } } } }, "responses": { "200": { "description": "Paginated transactions. Response shape depends on `source` in the request body.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "CardTransactionsResponse", "allOf": [ { "$ref": "#/components/schemas/TransactionResponse" } ], "example": { "links": { "next": null }, "pagination": { "pageSize": 20, "totalCount": 41, "nextCursor": "MTI7eyJ0cmFuc2FjdGlvbklkIjoiODA4MTUxOSIsImNyZWF0ZWRBdCI6IjE3NDY1NTUzMDI1MTIifq", "hasNext": true }, "data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "productType": "credit_line", "company": { "id": "361c697b-8d82-11ec-a51a-0ea06e4de10b", "name": "Acme Corporation" }, "user": { "id": "d5d5c940-3c58-4ecc-b772-fe20e764ed70", "name": "John Doe", "email": "john.doe@acmecorp.com" }, "card": { "id": "c8ddf33f-6244-4218-af7e-7a6fe0b13528", "name": "Travel Card", "type": "Physical", "number": "9876" }, "merchant": { "name": "STARBUCKS SAO PAULO BRA" }, "transactionType": "debit", "transactionDate": "2025-01-29 16:22:51", "settlementDate": "2025-01-30 08:00:03", "transactionAmount": 741.33, "transactionCurrency": "BRL", "localTransactionAmount": 127.59, "localTransactionCurrency": "USD" } ] } }, { "title": "TravelTransactionResponse", "allOf": [ { "$ref": "#/components/schemas/TravelTransactionResponse" } ], "example": { "links": { "next": null }, "pagination": { "pageSize": 100, "totalCount": 5, "nextCursor": "cursor-abc", "hasNext": true }, "data": [ { "transactionId": "123e4567-e89b-12d3-a456-426614174000", "transactionDate": "2025-01-29 16:22:51", "merchantName": "Starbucks", "transactionAmount": 741.33, "transactionCurrency": "BRL", "localAmount": 127.59, "localCurrency": "USD", "transactionType": "debit", "merchantCategoryCode": "5814", "cardholderName": "John Doe", "cardName": "Travel Card", "cardId": "c8ddf33f-6244-4218-af7e-7a6fe0b13528", "authorizationCode": "123456", "metadata": { "reservation_code": "abc123", "passenger_name": "John Doe" }, "restrictions": { "spendLimit": 1000 } } ] } } ] } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorDto" }, "examples": { "pageSizeExceedsCardsLimit": { "summary": "pageSize exceeds limit for source=cards", "value": { "statusCode": 400, "message": "pageSize must not exceed 50 for source=cards" } }, "pageSizeExceedsTravelLimit": { "summary": "pageSize exceeds maximum allowed value", "value": { "statusCode": 400, "message": "Bad Request", "errors": [ { "property": "pageSize", "constraints": { "max": "pageSize must not be greater than 100" } } ] } }, "invalidCardIdUuid": { "summary": "cardIds contains a non-UUID value", "value": { "statusCode": 400, "message": "Bad Request", "errors": [ { "property": "cardIds", "constraints": { "isUuid": "each value in cardIds must be a UUID" } } ] } }, "emptyCardIds": { "summary": "cardIds is an empty array", "value": { "statusCode": 400, "message": "Bad Request", "errors": [ { "property": "cardIds", "constraints": { "arrayNotEmpty": "cardIds should not be empty" } } ] } }, "startDateAfterEndDate": { "summary": "startDate is after endDate", "value": { "statusCode": 400, "message": "Bad Request", "errors": [ { "property": "startDate", "constraints": { "isValidDateRangeWith": "startDate must be before or equal to endDate" } } ] } }, "futureStartDate": { "summary": "startDate is a future date", "value": { "statusCode": 400, "message": "Bad Request", "errors": [ { "property": "startDate", "constraints": { "isNotFutureDate": "startDate must not be a future date" } } ] } }, "futureEndDate": { "summary": "endDate is a future date", "value": { "statusCode": 400, "message": "Bad Request", "errors": [ { "property": "endDate", "constraints": { "isNotFutureDate": "endDate must not be a future date" } } ] } }, "missingSource": { "summary": "source is missing", "value": { "statusCode": 400, "message": "Bad Request", "errors": [ { "property": "source", "constraints": { "isEnum": "source must be one of the following values: cards, travel" } } ] } }, "invalidSource": { "summary": "source is invalid", "value": { "statusCode": 400, "message": "Bad Request", "errors": [ { "property": "source", "constraints": { "isEnum": "source must be one of the following values: cards, travel" } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } } } }, "/v1/cards/{id}": { "get": { "operationId": "CardsController.getCard", "parameters": [ { "in": "path", "name": "id", "description": "Unique identifier of a card.", "required": true, "schema": { "pattern": "[^\\/#\\?]+?", "type": "string" } }, { "required": false, "name": "Accept-Language", "example": "en-US", "description": "Language code for localization.", "schema": { "type": "string", "enum": [ "en-US", "es-MX", "pt-BR" ], "default": "en-US" }, "in": "header" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardDetailsDto" } } }, "description": "Card details." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "Retrieve a card", "description": "You can get the card details by the card unique id.", "tags": [ "Cards" ], "security": [ { "OAuth2ClientCredentials": [ "cards:read" ] } ] }, "patch": { "operationId": "CardsController.updateCard", "parameters": [ { "in": "path", "name": "id", "description": "Unique identifier of a card.", "required": true, "schema": { "pattern": "[^\\/#\\?]+?", "type": "string" } }, { "required": false, "name": "Accept-Language", "example": "en-US", "description": "Language code for localization.", "schema": { "type": "string", "enum": [ "en-US", "es-MX", "pt-BR" ], "default": "en-US" }, "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardUpdateDto" } } }, "description": "CardUpdateDto", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardDto" } } }, "description": "Card details." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "Update a card", "description": "You can update card configuration by the card unique id.", "tags": [ "Cards" ], "security": [ { "OAuth2ClientCredentials": [ "cards:write" ] } ] }, "delete": { "operationId": "CardsController.deleteCard", "parameters": [ { "in": "path", "name": "id", "description": "Unique identifier of a card.", "required": true, "schema": { "pattern": "[^\\/#\\?]+?", "type": "string" } }, { "required": false, "name": "Accept-Language", "example": "en-US", "description": "Language code for localization.", "schema": { "type": "string", "enum": [ "en-US", "es-MX", "pt-BR" ], "default": "en-US" }, "in": "header" } ], "responses": { "204": { "content": { "application/json": {} }, "description": "Card deleted." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "Delete a card", "description": "You can delete a card by the card unique id.", "tags": [ "Cards" ], "security": [ { "OAuth2ClientCredentials": [ "cards:write" ] } ] } }, "/v1/cards/mcc/categories": { "get": { "operationId": "CardsController.getMccCategories", "parameters": [ { "in": "header", "required": false, "name": "Accept-Language", "example": "en-US", "description": "Language code for localization.", "schema": { "type": "string", "enum": [ "en-US", "es-MX", "pt-BR" ], "default": "en-US" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MccCategoriesResponse" } } }, "description": "List of merchant categories with their associated merchant category codes." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "List all MCC categories", "description": "You can list all MCC categories.", "tags": [ "Cards" ], "security": [ { "OAuth2ClientCredentials": [ "cards:read" ] } ] } }, "/v1/transactions": { "get": { "deprecated": true, "operationId": "TransactionsController.getTransactions", "parameters": [ { "in": "query", "name": "pageCursor", "required": false, "schema": { "type": "string" }, "description": "Page number to retrieve.", "example": "6e6578742d637572736f722d6578616d706c652d6e6578742d637572736f722d6578616d706c652d6e" }, { "in": "query", "name": "pageSize", "required": false, "schema": { "type": "number", "default": 20 }, "description": "Number of transactions returned by page." }, { "in": "query", "name": "startDate", "required": false, "schema": { "type": "string", "pattern": "\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d.\\d+Z?", "default": "previous day at 00:00:00" }, "description": "Transactions occurring on or after this date will be included.", "example": "2025-01-29 15:12:49" }, { "in": "query", "name": "endDate", "required": false, "schema": { "type": "string", "pattern": "\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d.\\d+Z?", "default": "previous day at 23:59:59" }, "description": "Transactions occurring on or before this date will be included. Limitations - must be greater than the startDate.", "example": "2025-01-30 17:35:55" }, { "required": false, "name": "Accept-Language", "example": "en-US", "description": "Language code used for localization.", "schema": { "type": "string", "enum": [ "en-US", "es-MX", "pt-BR" ], "default": "en-US" }, "in": "header" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" } } }, "description": "List of all transactions with all details." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "Get a list of card transactions", "description": "**Deprecated.** Use [`POST /v1/cards/transactions`](#tag/Cards/operation/CardsController.postCardTransactions) with `\"source\": \"cards\"` instead.\n\nYou get a list of card transactions belonging to your company.\n", "tags": [ "Transactions" ], "security": [ { "OAuth2ClientCredentials": [ "transactions:read", "transactions:multiple:read" ] } ] } }, "/v1/payments/transactions": { "get": { "operationId": "PaymentsController.getTransactions", "parameters": [ { "in": "query", "name": "pageCursor", "required": false, "schema": { "type": "string", "nullable": true, "default": null }, "description": "Page number to retrieve.", "example": 2 }, { "in": "query", "name": "pageSize", "required": false, "schema": { "type": "number", "minimum": 1, "maximum": 500, "default": 20 }, "description": "Number of items returned per page.", "example": 15 }, { "in": "query", "name": "startDate", "required": false, "schema": { "type": "string", "pattern": "\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d.\\d+Z?", "default": "previous day at 00:00:00" }, "description": "Transactions occurring on or after this date will be included.", "example": "2025-01-29 15:12:49" }, { "in": "query", "name": "endDate", "required": false, "schema": { "type": "string", "pattern": "\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d.\\d+Z?", "default": "previous day at 23:59:59" }, "description": "Transactions occurring on or before this date will be included. Limitations - must be greater than the startDate.", "example": "2025-01-30 17:35:55" }, { "required": false, "name": "Accept-Language", "example": "en-US", "description": "Language code used for localization.", "schema": { "type": "string", "enum": [ "en-US", "es-MX", "pt-BR" ], "default": "en-US" }, "in": "header" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTransactionResponse" } } }, "description": "List of all completed payment transactions sorted by creation date." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "Get a list of payment transactions", "description": "You can get all completed payment transactions filtered by date range.", "tags": [ "Transactions" ], "security": [ { "OAuth2ClientCredentials": [ "transactions:read", "transactions:multiple:read" ] } ] } }, "/v1/boletos": { "get": { "operationId": "BoletosController.getBoletos", "parameters": [ { "in": "query", "name": "page", "schema": { "minimum": 1, "type": "number", "description": "The page number to retrieve.", "default": 1, "example": 1 } }, { "in": "query", "name": "pageSize", "schema": { "maximum": 500, "type": "number", "minimum": 1, "description": "Number of items per page.", "default": 20, "example": 20 } }, { "in": "header", "name": "Accept-Language", "example": "en-US", "description": "Language code for localization.", "schema": { "type": "string", "enum": [ "en-US", "es-MX", "pt-BR" ], "default": "en-US" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoletosPageDto" } } }, "description": "List of boletos." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "List Boletos", "description": "Retrieves a paginated list of boletos.", "tags": [ "Boletos" ], "security": [ { "OAuth2ClientCredentials": [ "boletos:read" ] } ] }, "post": { "operationId": "BoletosController.createBoleto", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoletoCreateDto" } } }, "description": "BoletoCreateDto", "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoletoDto" } } }, "description": "Creates a boleto and returns its details." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "Create Boleto", "description": "Creates a new boleto, available for immediate payment.", "tags": [ "Boletos" ], "parameters": [ { "required": false, "name": "Accept-Language", "example": "en-US", "description": "Language code for localization.", "schema": { "type": "string", "enum": [ "en-US", "es-MX", "pt-BR" ], "default": "en-US" }, "in": "header" } ], "security": [ { "OAuth2ClientCredentials": [ "boletos:write" ] } ] } }, "/v1/boletos/{id}": { "get": { "operationId": "BoletosController.getBoleto", "parameters": [ { "in": "path", "name": "id", "description": "Boleto ID (UUID v4).", "required": true, "schema": { "pattern": "[^\\/#\\?]+?", "type": "string" } }, { "required": false, "name": "Accept-Language", "example": "en-US", "description": "Language code for localization.", "schema": { "type": "string", "enum": [ "en-US", "es-MX", "pt-BR" ], "default": "en-US" }, "in": "header" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoletoDto" } } }, "description": "Boleto details." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "Get Boleto by ID", "description": "Retrieves a specific boleto by its ID.", "tags": [ "Boletos" ], "security": [ { "OAuth2ClientCredentials": [ "boletos:read" ] } ] } }, "/v1/boletos/{id}/cancel": { "post": { "operationId": "BoletosController.cancelBoleto", "parameters": [ { "in": "path", "name": "id", "description": "Boleto ID (UUID v4).", "required": true, "schema": { "pattern": "[^\\/#\\?]+?", "type": "string" } }, { "required": false, "name": "Accept-Language", "example": "en-US", "description": "Language code for localization.", "schema": { "type": "string", "enum": [ "en-US", "es-MX", "pt-BR" ], "default": "en-US" }, "in": "header" } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoletoDto" } } }, "description": "Cancels a boleto and returns its details." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "Cancel Boleto", "description": "Cancels a registered boleto by its ID.", "tags": [ "Boletos" ], "security": [ { "OAuth2ClientCredentials": [ "boletos:write" ] } ] } }, "/v1/boletos/{id}/extend": { "post": { "operationId": "BoletosController.extendBoleto", "parameters": [ { "in": "path", "name": "id", "description": "Boleto ID (UUID v4).", "required": true, "schema": { "pattern": "[^\\/#\\?]+?", "type": "string" } }, { "required": false, "name": "Accept-Language", "example": "en-US", "description": "Language code for localization.", "schema": { "type": "string", "enum": [ "en-US", "es-MX", "pt-BR" ], "default": "en-US" }, "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoletoExtendDto" } } }, "description": "BoletoExtendDto", "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoletoDto" } } }, "description": "Extends a boleto's due date and returns its details." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "description": "Default response", "headers": { "x-trace-id": { "schema": { "type": "string", "description": "Request Trace ID" } } } } }, "summary": "Extend Boleto", "description": "Requests a due-date extension for a registered boleto.", "tags": [ "Boletos" ], "security": [ { "OAuth2ClientCredentials": [ "boletos:write" ] } ] } } }, "security": [ { "OAuth2ClientCredentials": [ "cards:read", "cards:write", "transactions:read", "transactions:multiple:read", "boletos:read", "boletos:write", "webhooks:read", "webhooks:write" ] } ], "servers": [ { "url": "https://public-sandbox.tryjeeves.com" }, { "url": "https://public-api.jeev.es" } ] }