{ "openapi": "3.1.0", "info": { "title": "Ripio Ramp API", "version": "v1", "description": "API for Ripio ramp services, enabling partners to integrate On-Ramp, Off-Ramp, customer management, KYC processes, and other financial functionalities. This API is RESTful, uses JSON for requests and responses, and standard HTTP status codes. This document is based on the 'onramp-api.pdf' provided and aims to be compliant with OpenAPI Specification v3.1.0. The PDF indicates that the API documentation is a draft and subject to change." }, "servers": [ { "url": "https://skala-sandbox.ripio.com", "description": "Sandbox environment" }, { "url": "https://skala.ripio.com", "description": "Production environment" } ], "components": { "securitySchemes": { "BasicAuth": { "type": "http", "scheme": "basic", "description": "Use Basic Auth with base64 encoded `client_id:client_secret`." }, "BearerToken": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Access token obtained via [/oauth2/token/](/ramps-api/authentication/acquire-access-token). Use as `Authorization: Bearer `." } }, "schemas": { "TransactionLimitsResponse": { "type": "object", "description": "Flat map of per-transaction limits. Keys follow the pattern `{CURRENCY}_{ONRAMP|OFFRAMP}_TRANSACTION_{MIN|MAX}_LIMIT`. Values are amounts expressed in the fiat currency named in the key.", "additionalProperties": { "type": "number", "description": "Limit amount, expressed in the fiat currency named in the key." } }, "CreateSupportTicketRequest": { "type": "object", "required": [ "customerId", "summary", "description" ], "properties": { "customerId": { "type": "string", "format": "uuid", "description": "Your customer ID for the end user the ticket is raised on behalf of. The customer must exist and have an email address on file." }, "summary": { "type": "string", "maxLength": 240, "description": "Short, one-line summary of the issue." }, "description": { "type": "string", "maxLength": 5000, "description": "Detailed description of the issue." }, "files": { "type": "array", "description": "Optional file attachments (e.g. screenshots). Up to 5 files per request, each up to 25 MB, and up to 50 MB in total. Allowed extensions: jpg, jpeg, png, webp, mp4, mov, avi, webm, pdf.", "items": { "type": "string", "format": "binary" } } } }, "SupportTicketResponse": { "type": "object", "required": [ "ticketId", "status", "issueKey" ], "properties": { "ticketId": { "type": "string", "format": "uuid", "description": "Ripio's identifier for the support ticket. Use it to correlate the Support Ticket webhook events, or to look up the ticket's status on demand via the Retrieve Support Ticket endpoint." }, "status": { "type": "string", "enum": [ "PENDING", "CREATED", "FAILED" ], "description": "Lifecycle status of the ticket. `PENDING`: accepted and being processed (no reference yet). `CREATED`: successfully registered in Ripio's support system; `issueKey` is populated. `FAILED`: the ticket could not be registered." }, "issueKey": { "type": [ "string", "null" ], "description": "Human-readable reference of the ticket in Ripio's support system (e.g. `SUP-1234`). `null` until the ticket reaches the `CREATED` status." } } }, "ErrorResponse": { "type": "object", "properties": { "code": { "type": "integer", "description": "Application-specific error code." }, "type": { "type": "string", "description": "Type of error or exception." }, "detail": { "type": "object", "properties": { "message": { "type": "string", "description": "Detailed error message." } }, "additionalProperties": true }, "status": { "type": "integer", "description": "HTTP status code." } }, "required": [ "code", "type", "detail", "status" ] }, "PaginatedFiatAccountList": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of items across all pages." }, "next": { "type": [ "string", "null" ], "format": "uri", "description": "URL to the next page of results. Null if no next page." }, "previous": { "type": [ "string", "null" ], "format": "uri", "description": "URL to the previous page of results. Null if no previous page." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/FiatAccount" }, "description": "Array of fiat account objects for the current page." } } }, "PaginatedOnRampOrderList": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of items across all pages." }, "next": { "type": [ "string", "null" ], "format": "uri", "description": "URL to the next page of results. Null if no next page." }, "previous": { "type": [ "string", "null" ], "format": "uri", "description": "URL to the previous page of results. Null if no previous page." }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/OnRampTransactionDetail" }, "description": "Array of On-Ramp order objects for the current page." } } }, "PaginatedOffRampOrderList": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of items across all pages." }, "next": { "type": [ "string", "null" ], "format": "uri", "description": "URL to the next page of results. Null if no next page." }, "previous": { "type": [ "string", "null" ], "format": "uri", "description": "URL to the previous page of results. Null if no previous page." }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/OffRampOrderTransactionDetail" }, "description": "Array of Off-Ramp order objects for the current page." } } }, "PaginatedAllOrdersList": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of items across all pages." }, "next": { "type": [ "string", "null" ], "format": "uri", "description": "URL to the next page of results. Null if no next page." }, "previous": { "type": [ "string", "null" ], "format": "uri", "description": "URL to the previous page of results. Null if no previous page." }, "transactions": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/OnRampTransactionDetail" }, { "$ref": "#/components/schemas/OffRampOrderTransactionDetail" } ] }, "description": "Array of order objects (both On-Ramp and Off-Ramp) for the current page." } } }, "PaginatedOnRampSessionList": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of items across all pages." }, "next": { "type": [ "string", "null" ], "format": "uri", "description": "URL to the next page of results. Null if no next page." }, "previous": { "type": [ "string", "null" ], "format": "uri", "description": "URL to the previous page of results. Null if no previous page." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/OnRampSessionResponse" }, "description": "Array of On-Ramp session objects for the current page." } } }, "PaginatedOffRampSessionList": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of items across all pages." }, "next": { "type": [ "string", "null" ], "format": "uri", "description": "URL to the next page of results. Null if no next page." }, "previous": { "type": [ "string", "null" ], "format": "uri", "description": "URL to the previous page of results. Null if no previous page." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/OffRampSessionResponse" }, "description": "Array of Off-Ramp session objects for the current page." } } }, "PaginatedSellAndPayList": { "type": "object", "properties": { "count": { "type": "integer", "description": "Total number of items across all pages." }, "next": { "type": [ "string", "null" ], "format": "uri", "description": "URL to the next page of results. Null if no next page." }, "previous": { "type": [ "string", "null" ], "format": "uri", "description": "URL to the previous page of results. Null if no previous page." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SellAndPayResponse" }, "description": "Array of Sell and Pay transaction objects for the current page." } } }, "AccessTokenResponse": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "The access token to be used for subsequent API calls.", "example": "UfpqHJaQEjV27rR6itJyhUz5x6eOxz" }, "expiresIn": { "type": "integer", "description": "The expiration time for the access token in seconds.", "example": 36000 }, "tokenType": { "type": "string", "description": "The type of token issued (always \"Bearer\" for this flow).", "example": "Bearer" }, "scope": { "type": "string", "description": "The scope of access granted by the token.", "example": "read write" } }, "required": [ "accessToken", "expiresIn", "tokenType" ] }, "CustomerCreationRequest": { "type": "object", "description": "Payload for creating a new customer.", "properties": { "email": { "type": "string", "format": "email", "description": "The email of the individual or juridical person.", "example": "individual@mail.com" }, "type": { "type": "string", "description": "The type of customer involved.", "enum": [ "INDIVIDUAL", "BUSINESS" ], "example": "INDIVIDUAL" } }, "required": [ "customerId", "email", "type" ] }, "CustomerUpdateRequest": { "type": "object", "description": "Payload for updating an existing customer.", "properties": { "email": { "type": "string", "format": "email", "description": "The new email for the customer.", "example": "new@email.com" } }, "required": [ "email" ] }, "CustomerResponse": { "type": "object", "description": "Response payload for a customer.", "properties": { "customerId": { "type": "string", "description": "A unique customer's ID.", "example": "7142b065-79c4-4f48-9e33-11b23bg689e2" }, "email": { "type": "string", "format": "email", "description": "The email of the individual or juridical person.", "example": "individual@mail.com" }, "isActive": { "type": "boolean", "description": "Whether the customer account is active. Returns `false` after the customer has been deactivated; in that case, operations on the customer's resources (KYC, fiat accounts, transactions, sessions) return 404.", "example": true }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time of customer's creation.", "example": "2024-04-10T18:17:07.702533Z" } } }, "KycCheckRequest": { "type": "object", "description": "Payload for checking KYC status. Email is optional.", "properties": { "email": { "type": "string", "format": "email", "description": "Optional email of the individual. If provided and customer doesn't have one, it will be assigned.", "example": "individual@mail.com" } } }, "KycCheckSuccessResponse": { "type": "object", "properties": { "detail": { "type": "string", "example": "kyc approved. Otp sent" } }, "required": [ "detail" ] }, "KycOtpValidationRequest": { "type": "object", "description": "Payload for validating OTP.", "properties": { "code": { "type": "string", "description": "The OTP code to verify.", "example": "123456" } }, "required": [ "code" ] }, "KycRequiredField": { "type": "object", "properties": { "fieldName": { "type": "string", "description": "The technical name of the required field used within the API." }, "required": { "type": "boolean", "description": "Indicates whether the field is mandatory (true) or optional (false)." }, "type": { "type": "string", "description": "The data type expected for the field value (e.g., TEXT, DATE, FILE_UPLOAD)." }, "choices": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } } }, "description": "A list of valid options for the field. This is only present for fields that have a predefined set of values." } }, "required": [ "fieldName", "required", "type" ] }, "KycRequirementsResponse": { "type": "object", "properties": { "kycRequiredFields": { "type": "array", "items": { "$ref": "#/components/schemas/KycRequiredField" } } }, "required": [ "kycRequiredFields" ] }, "KycSubmissionRequest": { "type": "object", "description": "Request body for KYC submission. Use `kycSubmission` + `redirectUrl` for the standard API flow, or only `redirectUrl` for the Ripio KYC delegated flow.", "properties": { "kycSubmission": { "type": "object", "description": "Customer KYC data. Fields vary by country \u2014 use `/kycRequirements/` to get the required fields for the customer's country. Not required when using the Ripio KYC delegated flow.", "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code (AR, MX, BR, CO).", "example": "AR" }, "first_name": { "type": "string", "example": "Mateo" }, "last_name": { "type": "string", "example": "Romero" }, "gender": { "type": "string", "description": "M or F (AR/BR/CO); H or M (MX).", "example": "M" }, "birthday": { "type": "string", "format": "date", "example": "1990-01-25" }, "nationality": { "type": "string", "example": "AR" }, "id_number_type": { "type": "string", "description": "Document type (e.g. DNI, CURP, CPF, CC).", "example": "DNI" }, "id_number": { "type": "string", "example": "11122233" }, "address": { "type": "string", "example": "Libertad" }, "address_number": { "type": "string", "example": "333" }, "address_flat": { "type": "string", "description": "Apartment / unit number (optional).", "example": "1" }, "postal_code": { "type": "string", "example": "1012" }, "district": { "type": "string", "example": "Chubut" }, "city": { "type": "string", "example": "Trelew" }, "state": { "type": "string", "description": "State code in ISO 3166-2 format (e.g. AR.CH, MX.JA).", "example": "AR.CH" }, "phone": { "type": "string", "description": "Phone number in E.164 format.", "example": "+542211228855" }, "personal_activity": { "type": "string", "description": "Occupation/activity code from `/kycRequirements/`.", "example": "AR.6" }, "personal_activity_other": { "type": "string", "description": "Free-text description when activity code requires it (optional)." }, "net_income": { "type": "string", "description": "Annual net income (required for some countries/activities).", "example": "10000" }, "registered_tax_payer": { "type": "boolean", "description": "Whether the customer is a registered tax payer (AR only).", "example": false }, "cuit": { "type": "string", "description": "Argentine tax ID (AR only). Required. Pass the customer's CUIL when `registered_tax_payer` is `false` (individual), or their CUIT when `registered_tax_payer` is `true` (registered taxpayer).", "example": "20111222330" }, "rfc": { "type": "string", "description": "Mexican tax ID (RFC). MX only.", "example": "LOJO951119Q18" }, "birthday_place": { "type": "string", "description": "City of birth. MX only.", "example": "Guadalajara" }, "date_of_issue": { "type": "string", "format": "date", "description": "ID issue date. MX only.", "example": "2024-01-01" }, "date_of_expiration": { "type": "string", "format": "date", "description": "ID expiration date. MX only.", "example": "2034-01-01" }, "terms_conditions": { "type": "boolean", "description": "Acceptance of terms and conditions. Required for MX.", "example": true }, "address_photo": { "type": "string", "format": "byte", "description": "Proof of address document as a base64-encoded image (e.g. JPEG or PNG, max 5 MB). Required for MX.", "example": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..." } }, "required": [ "country", "first_name", "last_name", "gender", "birthday", "nationality", "id_number_type", "id_number", "address", "address_number", "postal_code", "district", "city", "state", "phone" ] }, "redirectUrl": { "type": "string", "format": "uri", "description": "URL to redirect the user after completing the KYC flow. Required for the Ripio KYC delegated flow; optional for the API flow.", "example": "https://www.example.com/" } } }, "KycSubmissionResponse": { "type": "object", "properties": { "submissionId": { "type": "string", "format": "uuid", "description": "Unique identifier for the submitted KYC data." }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time the KYC submission was created (UTC format)." }, "providerUrl": { "type": "string", "format": "url", "description": "Points to a third-party KYC provider's widget to handle file uploads and liveness checks. Only available in production." } }, "required": [ "submissionId", "createdAt", "providerUrl" ] }, "KycSubmissionDetailResponse": { "type": "object", "properties": { "customerId": { "type": "string", "format": "uuid", "description": "Unique identifier for the customer." }, "status": { "type": "string", "enum": [ "IN_REVIEW", "COMPLETED", "FAILED" ], "description": "Current status of the KYC submission. IN_REVIEW: KYC is being reviewed, COMPLETED: KYC has been approved, FAILED: KYC was rejected." }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time the KYC submission was created (UTC format)." } }, "required": [ "customerId", "status", "createdAt" ] }, "CreateDepositAccountRequest": { "type": "object", "properties": { "paymentMethodType": { "type": "string", "description": "The payment method type for the deposit account.", "example": "bank_transfer" } }, "required": [ "paymentMethodType" ] }, "FiatAccountCreationRequest": { "type": "object", "properties": { "customerId": { "type": "string", "format": "uuid", "description": "The unique identifier of the customer for whom the account is being created." }, "paymentMethodType": { "type": "string", "description": "An enumerated value specifying the type of fiat account. Valid options depend on supported payment rails. (e.g., bank_transfer)" }, "accountFields": { "type": "object", "description": "A dictionary containing additional information required for the specific fiat account type. Fields depend on 'paymentMethodType and are defined by /fiatAccounts/requirements/.", "additionalProperties": true, "examples": [ { "alias_or_cvu_destination": "0100000000000000000001" }, { "clabe_destination": "706180196550550550" }, { "key_value": "@ABC123" }, { "counterparty_type": "cc", "counterparty_fullname": "Santiago Garc\u00eda", "counterparty_id_type": "cc", "counterparty_id_number": "1234567890", "beneficiary_institution": "1001", "account_number": "12345678901234" } ] } }, "required": [ "customerId", "paymentMethodType", "accountFields" ] }, "FiatAccount": { "type": "object", "properties": { "fiatAccountId": { "type": "string", "format": "uuid", "description": "The unique identifier of the fiat account." }, "fiatAccountFields": { "type": "object", "description": "A dictionary containing the details provided for the fiat account.", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the fiat account was created (UTC format)." }, "status": { "type": "string", "description": "An enumerated value specifying the fiat account status.", "enum": [ "UNCONFIRMED", "PROCESSING", "ENABLED", "DISABLED" ], "example": "PROCESSING" }, "metadata": { "type": "object", "nullable": true, "description": "Additional metadata associated with the fiat account. For Argentina accounts, this contains pre-validation data (e.g., CVU holder information) returned during account creation.", "additionalProperties": true }, "paymentMethodType": { "type": "string", "description": "Type of the fiat account." }, "customerId": { "type": "string", "format": "uuid", "description": "The unique identifier of the customer owning this account." } }, "required": [ "fiatAccountId", "fiatAccountFields", "createdAt", "status", "paymentMethodType", "customerId" ] }, "FiatAccountRequirementField": { "type": "object", "properties": { "fieldName": { "type": "string", "description": "The technical name of the required field used within the API." }, "required": { "type": "boolean", "description": "Indicates whether the field is mandatory (true) or optional (false)." }, "type": { "type": "string", "description": "The data type expected for the field value (e.g., TEXT, NUMBER)." } }, "required": [ "fieldName", "required", "type" ] }, "FiatAccountRequirementsResponse": { "type": "array", "items": { "$ref": "#/components/schemas/FiatAccountRequirementField" } }, "BankCode": { "type": "object", "description": "Represents a bank with its code and allowed account types. Only available for Colombia.", "properties": { "code": { "type": "string", "description": "The unique bank code used as the beneficiary_institution value when creating fiat accounts." }, "name": { "type": "string", "description": "The display name of the bank." }, "type": { "type": "array", "items": { "type": "string" }, "description": "The allowed counterparty_types for this bank (e.g., cc, ch, dp)." }, "logo": { "type": "string", "format": "url", "description": "URL of the bank's logo." } }, "required": [ "code", "name", "type", "logo" ] }, "Fee": { "type": "object", "properties": { "amount": { "type": "string", "description": "The amount of the fee.", "example": "0.37" }, "type": { "type": "string", "description": "The type of fee (e.g., Network Fee).", "example": "Gas Price" }, "currency": { "type": "string", "description": "The currency in which the fee amount is expressed.", "example": "ARS" }, "appliesOnFromAmount": { "type": "boolean", "description": "Indicates whether it deducts the amount on the fromAmount or not. Always the negation of appliesOnToAmount." }, "appliesOnToAmount": { "type": "boolean", "description": "Indicates whether it deducts the amount on the toAmount or not. Always the negation of appliesOnFromAmount." } }, "required": [ "amount", "type", "currency", "appliesOnFromAmount", "appliesOnToAmount" ] }, "QuoteCreationRequest": { "type": "object", "properties": { "fromCurrency": { "type": "string", "description": "The source currency for the conversion.", "example": "ARS" }, "toCurrency": { "type": "string", "description": "The target currency for the conversion.", "example": "USDC" }, "fromAmount": { "type": "string", "description": "The amount of the source currency to be converted.", "example": "1500" }, "chain": { "type": "string", "description": "The blockchain network to be used for the conversion (applicable for certain cryptocurrencies).", "example": "ETHEREUM_SEPOLIA" }, "paymentMethodType": { "type": "string", "description": "The desired payment method for the conversion (e.g., `bank_transfer`, `breb`, `r2p_bancolombia`, `r2p_nequi`). Note: `breb`, `r2p_bancolombia` and `r2p_nequi` are only available for Colombia. Additionally, `r2p_bancolombia` and `r2p_nequi` are only available for on-ramp operations.", "example": "bank_transfer" } }, "required": [ "fromCurrency", "toCurrency", "fromAmount", "chain", "paymentMethodType" ] }, "QuoteResponse": { "type": "object", "properties": { "quoteId": { "type": "string", "format": "uuid", "description": "Unique identifier for the quote.", "example": "8142b065-79c4-4f48-9e33-11b17bc658d4" }, "fromCurrency": { "type": "string", "description": "The source currency for the conversion.", "example": "ARS" }, "toCurrency": { "type": "string", "description": "The target currency for the conversion.", "example": "USDC" }, "fromAmount": { "type": "string", "description": "The amount of the source currency to be converted.", "example": "1500.00000000" }, "finalFromAmount": { "type": "string", "description": "The amount of the source currency after fees deduction.", "example": "1400.00000000" }, "toAmount": { "type": "string", "description": "The amount of the target currency received after the conversion.", "example": "1.42857143" }, "finalToAmount": { "type": "string", "description": "The amount of the target currency after fees deduction.", "example": "1.32857143" }, "rate": { "type": "string", "description": "The exchange rate applied for the conversion.", "example": "1050.00000000" }, "expiration": { "type": "string", "format": "date-time", "description": "The date and time when the quote expires (UTC).", "example": "2024-04-10T18:17:07.702533Z" }, "fees": { "type": "array", "items": { "$ref": "#/components/schemas/Fee" } } }, "required": [ "quoteId", "fromCurrency", "toCurrency", "fromAmount", "finalFromAmount", "toAmount", "finalToAmount", "rate", "expiration", "fees" ] }, "FiatPaymentInstructionItem": { "type": "object", "properties": { "fieldName": { "type": "string", "description": "Name of the instruction field.", "example": "cvu" }, "value": { "type": "string", "description": "Value of the instruction field.", "example": "0100000000000000000001" }, "type": { "type": "string", "description": "Data type of the instruction field.", "example": "TEXT" } }, "required": [ "fieldName", "value", "type" ] }, "OnRampTransactionDetail": { "type": "object", "description": "Details of an on-ramp transaction.", "properties": { "transactionId": { "type": "string", "format": "uuid", "description": "Unique identifier for the on-ramp transaction.", "example": "21d8a046-3221-4b43-a301-0f9adcdd9a45" }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time the on-ramp transaction was created." }, "customerId": { "type": "string", "format": "uuid", "description": "Customer's unique identifier." }, "quoteId": { "type": "string", "format": "uuid", "description": "Reference to the original quote used for this transaction." }, "fromCurrency": { "type": "string", "description": "The source currency (fiat) used in the on-ramp transaction.", "example": "ARS" }, "toCurrency": { "type": "string", "description": "The target cryptocurrency received in the on-ramp transaction.", "example": "USDC" }, "amount": { "type": "string", "description": "The amount of the target cryptocurrency received (based on the original quote)." }, "chain": { "type": "string", "description": "The target blockchain network for the cryptocurrency deposit.", "example": "ETHEREUM_SEPOLIA" }, "metadata": { "type": "object", "description": "Additional metadata associated with the transaction.", "additionalProperties": true, "example": {} }, "txnHash": { "type": [ "string", "null" ], "description": "Transaction hash for the on-chain operation (null if not yet processed).", "example": null }, "paymentMethodType": { "type": "string", "description": "The payment method used for the fiat deposit.", "example": "bank_transfer" }, "depositAddress": { "type": "string", "description": "The customer's deposit address on the target blockchain." }, "status": { "type": "string", "description": "The current transaction status.", "enum": [ "ON_RAMP_DEPOSIT_RECEIVED", "ON_RAMP_TRADE_COMPLETED", "ON_RAMP_WITHDRAWAL_PROCESSING", "ON_RAMP_WITHDRAWAL_COMPLETED", "ON_RAMP_TRADE_CANCELLED", "ON_RAMP_ORDER_EXPIRED", "ON_RAMP_REFUND_COMPLETED" ], "example": "WITHDRAWAL_PENDING" }, "externalRef": { "type": "string", "format": "uuid", "description": "Unique identifier for the order provided by the partner." }, "source": { "type": "string", "description": "Indicates the origin of the on-ramp order.", "enum": [ "ON_RAMP", "ON_RAMP_SESSION" ], "example": "ON_RAMP" }, "sender": { "type": [ "string", "null" ], "description": "Name of the holder of the originating fiat account (e.g. CVU/CLABE owner). Null when not provided by the fiat provider.", "example": "Juan P\u00e9rez" } }, "required": [ "transactionId", "createdAt", "customerId", "quoteId", "fromCurrency", "toCurrency", "amount", "chain", "paymentMethodType", "depositAddress", "status", "externalRef", "source" ] }, "OnRampOrderCreationRequest": { "type": "object", "properties": { "customerId": { "type": "string", "format": "uuid", "description": "Unique identifier for the customer.", "example": "b6cecc1f-c90d-424b-adaa-c82b780696c1" }, "quoteId": { "type": "string", "format": "uuid", "description": "Unique identifier for the quote obtained from the Quoting Endpoint.", "example": "8142b065-79c4-4f48-9e33-11b17bc658d4" }, "depositAddress": { "type": "string", "description": "The customer's deposit address on the chosen blockchain network.", "example": "0x4e88BBeFF059BDDF5BF90ee0816E86eDf4214b32" }, "externalRef": { "type": "string", "format": "uuid", "description": "Unique identifier for the order that is being created, provided by the partner.", "example": "e6c4f1ec-899f-43b5-8479-c2529e3f9c70" }, "extraData": { "type": "object", "description": "Additional data for the on-ramp order. Required for Colombia payment methods (`bank_transfer`, `r2p_bancolombia`, `r2p_nequi`).", "properties": { "callback": { "type": "string", "format": "uri", "description": "Callback URL for payment notifications. Required for Colombia payment methods (`bank_transfer`, `r2p_bancolombia`, `r2p_nequi`).", "example": "https://example.com/callback" }, "bankCode": { "type": "string", "description": "Bank code for Colombia `bank_transfer` payment method. Not required for `r2p_bancolombia` or `r2p_nequi`. Retrieve valid codes from `GET /api/v1/banks/`.", "example": "1001" } } } }, "required": [ "customerId", "quoteId", "depositAddress", "externalRef" ] }, "OnRampOrderResponse": { "type": "object", "properties": { "transaction": { "$ref": "#/components/schemas/OnRampTransactionDetail" }, "fiatPaymentInstructions": { "type": "object", "description": "Instructions for the customer to complete the fiat deposit. Structure varies depending on payment method and currency: `bank_transfer` (Argentina) returns `cvu` and optionally `alias` (a human-readable identifier that can be used instead of the CVU for transfers \u2014 to enable alias customization, contact the Ripio team), `bank_transfer` (Mexico) returns `clabe`, `bank_transfer` (Colombia) returns `paymentUrl`, `breb` returns `brebKey`, `r2p_bancolombia` returns `paymentUrl`, `r2p_nequi` returns `phoneNumber`. Methods backed by a persistent deposit account (`cvu`, `clabe`, `brebKey`) also include a `status` field (`processing`, `enabled` or `disabled`) indicating whether the deposit account is ready to operate; while `processing`, the deposit key/identifier may be `null`.", "additionalProperties": true, "examples": [ { "cvu": "0100000000000000000001", "alias": "juan.perez.ramp", "status": "enabled" }, { "cvu": "0100000000000000000001", "status": "enabled" }, { "clabe": "706180196550550550", "status": "enabled" }, { "paymentUrl": "https://example.com/payment/abc123" }, { "brebKey": "@ABC123", "status": "enabled" }, { "phoneNumber": "*****1234" } ] } }, "required": [ "transaction", "fiatPaymentInstructions" ] }, "OnRampSessionCreationRequest": { "type": "object", "properties": { "customerId": { "type": "string", "format": "uuid", "description": "Unique identifier for the customer.", "example": "fca6d32f-2f7e-4f7e-b224-8be0b92fa3f1" }, "paymentMethodType": { "type": "string", "description": "The payment method used for the fiat deposit (e.g., `bank_transfer`, `breb`). Note: `breb` is only available for Colombia.", "example": "bank_transfer" }, "chain": { "type": "string", "description": "The blockchain network to be used for the conversion.", "example": "ETHEREUM_SEPOLIA" }, "currency": { "type": "string", "description": "The target currency for the conversion.", "example": "USDC" }, "depositAddress": { "type": "string", "description": "The customer's deposit address on the chosen blockchain network.", "example": "0x4e88BBeFF059BDDF5BF90ee0816E86eDf4214b32" } }, "required": [ "customerId", "paymentMethodType", "chain", "currency", "depositAddress" ] }, "OnRampSessionResponse": { "type": "object", "properties": { "sessionId": { "type": "string", "format": "uuid", "description": "Unique identifier for the created on-ramp session." }, "customerId": { "type": "string", "format": "uuid", "description": "Unique identifier for the customer associated with the session." }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time the on-ramp session was created." }, "currency": { "type": "string", "description": "The target crypto currency for every on-ramp transaction performed with the created session." }, "chain": { "type": "string", "description": "The blockchain network to be used for the conversion." }, "depositAddress": { "type": "string", "description": "The customer's deposit address on the chosen blockchain network." }, "fiatPaymentInstructions": { "type": "object", "description": "Instructions for the customer to complete the fiat deposit. Structure varies depending on payment method and currency: `bank_transfer` (Argentina) returns `cvu` and optionally `alias` (a human-readable identifier that can be used instead of the CVU for transfers \u2014 to enable alias customization, contact the Ripio team), `bank_transfer` (Mexico) returns `clabe`, `breb` (Colombia) returns `brebKey`. Methods backed by a persistent deposit account (`cvu`, `clabe`, `brebKey`) also include a `status` field (`processing`, `enabled` or `disabled`) indicating whether the deposit account is ready to operate; while `processing`, the deposit key/identifier may be `null`.", "additionalProperties": true, "examples": [ { "cvu": "0000465160000000070078", "alias": "juan.perez.ramp", "status": "enabled" }, { "cvu": "0000465160000000070078", "status": "enabled" }, { "clabe": "706180196550550550", "status": "enabled" }, { "brebKey": "@E6JZKEPG5S", "status": "enabled" } ] }, "transactions": { "type": "array", "description": "A list containing every transaction that has been either started or completed through this session. On creation, will always be empty.", "items": { "$ref": "#/components/schemas/OnRampTransactionDetail" } } }, "required": [ "sessionId", "customerId", "createdAt", "currency", "chain", "depositAddress", "fiatPaymentInstructions", "orders" ] }, "OffRampDepositAddressItem": { "type": "object", "properties": { "chain": { "type": "string", "description": "The cryptocurrency blockchain for the deposit address.", "example": "ETHEREUM" }, "address": { "type": "string", "description": "The deposit address for the corresponding blockchain.", "example": "0x1234567890AbCdEf1234567890AbCdEf1234567890" } }, "required": [ "chain", "address" ] }, "OffRampOrderTransactionDetail": { "type": "object", "description": "Details of an off-ramp transaction.", "properties": { "transactionId": { "type": "string", "format": "uuid", "description": "Unique identifier for the off-ramp transaction." }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time the off-ramp transaction was created." }, "customerId": { "type": "string", "format": "uuid", "description": "Customer's unique identifier." }, "quoteId": { "type": "string", "format": "uuid", "description": "Reference to the original quote used for this transaction." }, "fromCurrency": { "type": "string", "description": "The source cryptocurrency being off-ramped.", "example": "USDC" }, "toCurrency": { "type": "string", "description": "The target fiat currency received.", "example": "ARS" }, "amount": { "type": "string", "description": "The amount of the target currency transferred or to be transferred." }, "chain": { "type": "string", "description": "The cryptocurrency blockchain for the deposit address.", "example": "ETHEREUM" }, "status": { "type": "string", "description": "The current transaction status (subset of OnRamp statuses, specific OffRamp statuses to be confirmed from full API spec if different)." }, "txnHash": { "type": "string", "description": "The transaction hash for the on-chain operation (crypto deposit)." }, "providerId": { "type": "string", "description": "The fiat withdrawal provider's transaction identifier. Available for completed Argentine off-ramp orders." }, "finishedAt": { "type": "string", "description": "Date and time the fiat withdrawal was completed by the provider. Available for completed Argentine off-ramp orders." } }, "required": [ "transactionId", "createdAt", "customerId", "quoteId", "fromCurrency", "toCurrency", "amount", "chain", "status" ] }, "OffRampSessionCreationRequest": { "type": "object", "properties": { "fiatAccountId": { "type": "string", "format": "uuid", "description": "Unique identifier for the customer's chosen fiat account.", "example": "fca6d32f-2f7e-4f7e-b224-8be0b92fa3f1" } }, "required": [ "fiatAccountId" ] }, "OffRampSessionResponse": { "type": "object", "properties": { "sessionId": { "type": "string", "format": "uuid", "description": "Unique identifier for the created off-ramp session." }, "customerId": { "type": "string", "format": "uuid", "description": "Unique identifier for the customer associated with the session." }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time the off-ramp session was created." }, "toCurrency": { "type": "string", "description": "The target fiat currency for every off-ramp transaction performed with the created session." }, "paymentMethodType": { "type": "string", "description": "The fiat payment method through which the transactions will be performed." }, "fiatAccountId": { "type": "string", "format": "uuid", "description": "Unique identifier for the customer's chosen fiat account." }, "depositAddresses": { "type": "array", "description": "A list containing cryptocurrency deposit addresses for supported blockchains.", "items": { "$ref": "#/components/schemas/OffRampDepositAddressItem" } }, "transactions": { "type": "array", "description": "A list containing every transaction that has been either started or completed through this session. On creation, will always be empty.", "items": { "$ref": "#/components/schemas/OffRampOrderTransactionDetail" } } }, "required": [ "sessionId", "customerId", "createdAt", "toCurrency", "paymentMethodType", "fiatAccountId", "depositAddresses", "orders" ] }, "NetworkAsset": { "type": "object", "properties": { "name": { "type": "string", "description": "The asset name.", "example": "USDC" }, "contract_address": { "type": [ "string", "null" ], "description": "The contract address for that asset in the corresponding blockchain. Null if it's the native token.", "example": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238" } }, "required": [ "name", "contract_address" ] }, "NetworkResponseItem": { "type": "object", "properties": { "network_name": { "type": "string", "description": "The network name.", "example": "ETHEREUM" }, "assets": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkAsset" }, "description": "Array of available assets in the network. Shown only if include_currency is true." } }, "required": [ "network_name" ] }, "NetworksResponse": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkResponseItem" } }, "RatePair": { "type": "object", "properties": { "pair": { "type": "string", "description": "Base currency and Quote currency used to establish the exchange rate.", "example": "ETH_ARS" }, "last_buy_rate": { "type": "number", "format": "double", "description": "Last Buy market rate." }, "last_sell_rate": { "type": "number", "format": "double", "description": "Last Sell market rate." }, "final_buy_rate": { "type": "number", "format": "double", "description": "Represents the last buy market rate with fees applied." }, "final_sell_rate": { "type": "number", "format": "double", "description": "Represents the last sell market rate with fees applied." } }, "required": [ "pair", "last_buy_rate", "last_sell_rate", "final_buy_rate", "final_sell_rate" ] }, "RatesResponse": { "type": "array", "items": { "$ref": "#/components/schemas/RatePair" } }, "SimulateDepositRequest": { "type": "object", "properties": { "paymentMethodType": { "type": "string", "description": "The payment method type for the simulated deposit.", "example": "bank_transfer" }, "amount": { "type": "number", "description": "The amount of fiat to send.", "example": 2100 }, "alias_or_cvu": { "type": "string", "description": "Alias or CVU to which the deposit will be made (from onramp fiatPaymentInstructions). Used for ARS deposits.", "example": "0100000000000000000001" }, "clabe": { "type": "string", "description": "CLABE to which the deposit will be made (from onramp fiatPaymentInstructions). Used for MXN deposits.", "example": "706180196550550550" }, "payment_url": { "type": "string", "format": "uri", "description": "Payment URL to identify the order (from onramp fiatPaymentInstructions). Used for COP deposits.", "example": "https://example.com/payment/abc123" } }, "required": [ "paymentMethodType", "amount" ] }, "OnRampStandardEventTransaction": { "type": "object", "description": "Standard transaction object for most On-Ramp webhook events.", "properties": { "transactionId": { "type": "string", "format": "uuid", "description": "Unique identifier for the on-ramp transaction." }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time the on-ramp transaction was created." }, "customerId": { "type": "string", "format": "uuid", "description": "Unique identifier of the customer." }, "quoteId": { "type": "string", "format": "uuid", "description": "Reference to the original quote." }, "fromCurrency": { "type": "string", "description": "Source currency (fiat)." }, "toCurrency": { "type": "string", "description": "Target cryptocurrency." }, "amount": { "type": "string", "description": "Amount of target cryptocurrency." }, "chain": { "type": "string", "description": "Target blockchain network." }, "paymentMethodType": { "type": "string", "description": "Payment method used." }, "depositAddress": { "type": "string", "description": "Customer's deposit address." }, "txnHash": { "type": [ "string", "null" ], "description": "Transaction hash for the on-chain operation (present in relevant events like COMPLETED)." }, "source": { "type": "string", "description": "Indicates the origin of the on-ramp order.", "enum": [ "ON_RAMP", "ON_RAMP_SESSION" ] }, "sender": { "type": [ "string", "null" ], "description": "Name of the holder of the originating fiat account (e.g. CVU/CLABE owner). Null when not provided by the fiat provider.", "example": "Juan P\u00e9rez" } } }, "OnRampDepositRefundEventTransaction": { "type": "object", "description": "Transaction object for ON-RAMP.DEPOSIT.REFUNDED event.", "properties": { "transactionId": { "type": "string", "format": "uuid", "description": "Unique identifier for the deposit." }, "originAccountIdentifier": { "type": "string", "description": "Identifier of the account from which the deposit originated." }, "amount": { "type": "string", "description": "The amount received." }, "customerId": { "type": "string", "format": "uuid", "description": "Unique identifier of the customer." }, "paymentMethodType": { "type": "string", "description": "Payment method used." }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time the deposit was created." } } }, "OffRampEventTransaction": { "type": "object", "description": "Transaction object for Off-Ramp webhook events.", "properties": { "transactionId": { "type": "string", "format": "uuid", "description": "Unique identifier for the off-ramp transaction (session)." }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time the off-ramp session was created." }, "fiatAccountId": { "type": "string", "format": "uuid", "description": "Unique identifier for the customer's fiat account." }, "fromCurrency": { "type": "string", "description": "Source cryptocurrency." }, "toCurrency": { "type": "string", "description": "Target fiat currency." }, "amount": { "type": "string", "description": "Amount of source cryptocurrency (crypto deposit amount)." }, "chain": { "type": "string", "description": "Blockchain network used for crypto deposit." }, "address": { "type": "string", "description": "Cryptocurrency deposit address used by the customer." }, "status": { "type": "string", "description": "Current transaction status." }, "txnHash": { "type": "string", "description": "Transaction hash for the on-chain operation (crypto deposit)." } } }, "WebhookEventBase": { "type": "object", "properties": { "issueDatetime": { "type": "string", "format": "date-time", "description": "Date and time the event occurred (UTC).", "example": "2024-04-25T18:22:37Z" } }, "required": [ "eventType", "issueDatetime" ] }, "OnRampDepositReceivedPayload": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "example": "ON-RAMP.DEPOSIT.RECEIVED" }, "transaction": { "$ref": "#/components/schemas/OnRampStandardEventTransaction" } } } ] }, "OnRampTradeCompletedPayload": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "example": "ON-RAMP.TRADE.COMPLETED" }, "transaction": { "$ref": "#/components/schemas/OnRampStandardEventTransaction" } } } ] }, "OnRampWithdrawalProcessingPayload": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "example": "ON-RAMP.WITHDRAWAL.PROCESSING" }, "transaction": { "$ref": "#/components/schemas/OnRampStandardEventTransaction" } } } ] }, "OnRampWithdrawalCompletedPayload": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "example": "ON-RAMP.WITHDRAWAL.COMPLETED" }, "transaction": { "$ref": "#/components/schemas/OnRampStandardEventTransaction" } } } ] }, "OnRampOrderCancelledPayload": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "example": "ON-RAMP.ORDER.CANCELLED" }, "transaction": { "$ref": "#/components/schemas/OnRampStandardEventTransaction" } } } ] }, "OnRampOrderRefundedPayload": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "example": "ON-RAMP.ORDER.REFUNDED" }, "transaction": { "$ref": "#/components/schemas/OnRampStandardEventTransaction" } } } ] }, "OnRampDepositRefundedPayload": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "example": "ON-RAMP.DEPOSIT.REFUNDED" }, "transaction": { "$ref": "#/components/schemas/OnRampDepositRefundEventTransaction" } } } ] }, "OffRampDepositReceivedPayload": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "example": "OFF-RAMP.DEPOSIT.RECEIVED" }, "transaction": { "$ref": "#/components/schemas/OffRampEventTransaction" } } } ] }, "OffRampTradeCompletedPayload": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "example": "OFF-RAMP.TRADE.COMPLETED" }, "transaction": { "$ref": "#/components/schemas/OffRampEventTransaction" } } } ] }, "OffRampWithdrawalProcessingPayload": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "example": "OFF-RAMP.WITHDRAWAL.PROCESSING" }, "transaction": { "$ref": "#/components/schemas/OffRampEventTransaction" } } } ] }, "OffRampWithdrawalCompletedPayload": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "example": "OFF-RAMP.WITHDRAWAL.COMPLETED" }, "transaction": { "$ref": "#/components/schemas/OffRampEventTransaction" } } } ] }, "OffRampOrderCancelledPayload": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "example": "OFF-RAMP.ORDER.CANCELLED" }, "transaction": { "$ref": "#/components/schemas/OffRampEventTransaction" } } } ] }, "SellAndPayDepositReceivedPayload": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "example": "SELL_AND_PAY.DEPOSIT.RECEIVED" }, "transaction": { "$ref": "#/components/schemas/SellAndPayEventTransaction" } } } ] }, "SellAndPayDepositBlockedPayload": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "example": "SELL_AND_PAY.DEPOSIT.BLOCKED" }, "transaction": { "$ref": "#/components/schemas/SellAndPayEventTransaction" } } } ] }, "SellAndPayPaymentOrderCompletedPayload": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "example": "SELL_AND_PAY.PAYMENT_ORDER.COMPLETED" }, "transaction": { "$ref": "#/components/schemas/SellAndPayEventTransaction" } } } ] }, "SellAndPayDepositWithoutSellAndPayRefundProcessingPayload": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "example": "SELL_AND_PAY.DEPOSIT_WITHOUT_SELL_AND_PAY.REFUND_PROCESSING" }, "transaction": { "$ref": "#/components/schemas/SellAndPayDepositWithoutTransactionEvent" } } } ] }, "SellAndPayDepositRefundProcessingPayload": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "example": "SELL_AND_PAY.DEPOSIT.REFUND_PROCESSING" }, "transaction": { "$ref": "#/components/schemas/SellAndPayEventTransaction" } } } ] }, "SellAndPayEventTransaction": { "type": "object", "description": "Transaction object for Sell and Pay webhook events. Matches the SellAndPayWebhookSerializer structure.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the Sell and Pay transaction." }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time the Sell and Pay transaction was created." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Date and time when the transaction will expire." }, "customerId": { "type": "string", "format": "uuid", "description": "Unique identifier of the customer." }, "trade": { "anyOf": [ { "$ref": "#/components/schemas/SellAndPayTrade" }, { "type": "null" } ], "description": "Trade execution details. Will be null if the trade has not been executed yet." }, "paymentOrder": { "anyOf": [ { "$ref": "#/components/schemas/SellAndPayPaymentOrder" }, { "type": "null" } ], "description": "Payment order details for the merchant payment. Will be null if the payment order has not been created yet." }, "amount": { "type": "string", "description": "Payment amount in fiat currency to be paid to the merchant." }, "cryptoAmount": { "type": "string", "description": "Amount of cryptocurrency required/deposited." }, "paymentCurrency": { "type": "string", "description": "Fiat currency used for the QR code payment." }, "depositCurrency": { "type": "string", "description": "Cryptocurrency deposited by the customer." }, "depositNetwork": { "type": "string", "description": "Blockchain network used for the cryptocurrency deposit." }, "depositAddress": { "type": "string", "description": "Cryptocurrency address where the deposit was made." }, "status": { "type": "string", "description": "Current status of the Sell and Pay transaction." }, "cryptoDeposit": { "anyOf": [ { "$ref": "#/components/schemas/SellAndPayCryptoDeposit" }, { "type": "null" } ], "description": "Information about the cryptocurrency deposit made by the customer. Will be null until a deposit is detected on the blockchain." }, "refundTxnHash": { "type": [ "string", "null" ], "description": "Transaction hash for the refund transaction on the blockchain. Present when a refund has been processed." } } }, "SellAndPayDepositWithoutTransactionEvent": { "type": "object", "description": "Transaction object for SELL_AND_PAY.DEPOSIT_WITHOUT_SELL_AND_PAY.REFUND_PROCESSING event. This event has a different structure with only cryptoDeposit and refundTxnHash.", "properties": { "cryptoDeposit": { "$ref": "#/components/schemas/SellAndPayCryptoDeposit", "description": "Information about the cryptocurrency deposit that was received without an associated Sell and Pay transaction." }, "refundTxnHash": { "type": [ "string", "null" ], "description": "Transaction hash for the refund transaction on the blockchain. Will be present once the refund is processed." } } }, "AccountClosedPayload": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "example": "ACCOUNT.CLOSED" }, "account": { "type": "object", "description": "Account lifecycle payload.", "properties": { "customerId": { "type": "string", "format": "uuid", "description": "Partner-facing customer ID of the deactivated customer.", "example": "7142b065-79c4-4f48-9e33-11b23bg689e2" }, "isActive": { "type": "boolean", "description": "Always `false` for this event.", "example": false } }, "required": [ "customerId", "isActive" ] } }, "required": [ "account" ] } ] }, "AccountProcessingPayload": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "example": "ACCOUNT.PROCESSING" }, "account": { "type": "object", "description": "Deposit account readiness payload. Sent when the customer's fiat deposit account has been created and is being prepared. For payment methods whose deposit instructions are assigned asynchronously, the deposit key/identifier may not be available yet (an `ACCOUNT.ENABLED` event follows once it is).", "properties": { "customerId": { "type": "string", "format": "uuid", "description": "Partner-facing customer ID owning the deposit account.", "example": "7142b065-79c4-4f48-9e33-11b23bg689e2" }, "paymentMethodType": { "type": "string", "description": "The payment method the deposit account is for.", "example": "breb" }, "fiatPaymentInstructions": { "type": "object", "description": "Deposit instructions for the account. Same structure as the `fiatPaymentInstructions` returned by the on-ramp session and order endpoints, always including a `status` field. While the account is `processing`, the deposit key/identifier may be `null`.", "additionalProperties": true, "examples": [ { "brebKey": null, "status": "processing" }, { "clabe": null, "status": "processing" } ] } }, "required": [ "customerId", "paymentMethodType", "fiatPaymentInstructions" ] } }, "required": [ "account" ] } ] }, "AccountEnabledPayload": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "example": "ACCOUNT.ENABLED" }, "account": { "type": "object", "description": "Deposit account readiness payload. Sent when the customer's fiat deposit account becomes ready to operate. The `fiatPaymentInstructions` now carry the deposit details the end user needs to fund an on-ramp order, so polling the API after creation is not required.", "properties": { "customerId": { "type": "string", "format": "uuid", "description": "Partner-facing customer ID owning the deposit account.", "example": "7142b065-79c4-4f48-9e33-11b23bg689e2" }, "paymentMethodType": { "type": "string", "description": "The payment method the deposit account is for.", "example": "bank_transfer" }, "fiatPaymentInstructions": { "type": "object", "description": "Deposit instructions for the account. Same structure as the `fiatPaymentInstructions` returned by the on-ramp session and order endpoints, always including a `status` field set to `enabled`.", "additionalProperties": true, "examples": [ { "cvu": "0000465160000000070078", "status": "enabled" }, { "clabe": "706180196550550550", "status": "enabled" }, { "brebKey": "@E6JZKEPG5S", "status": "enabled" } ] } }, "required": [ "customerId", "paymentMethodType", "fiatPaymentInstructions" ] } }, "required": [ "account" ] } ] }, "AccountDisabledPayload": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "example": "ACCOUNT.DISABLED" }, "account": { "type": "object", "description": "Deposit account readiness payload. Sent when the customer's fiat deposit account becomes disabled and can no longer be operated. After this event the account should not be used for new on-ramp orders.", "properties": { "customerId": { "type": "string", "format": "uuid", "description": "Partner-facing customer ID owning the deposit account.", "example": "7142b065-79c4-4f48-9e33-11b23bg689e2" }, "paymentMethodType": { "type": "string", "description": "The payment method the deposit account is for.", "example": "bank_transfer" }, "fiatPaymentInstructions": { "type": "object", "description": "Deposit instructions for the account. Same structure as the `fiatPaymentInstructions` returned by the on-ramp session and order endpoints, always including a `status` field set to `disabled`.", "additionalProperties": true, "examples": [ { "cvu": "0000465160000000070078", "status": "disabled" }, { "clabe": "706180196550550550", "status": "disabled" }, { "brebKey": "@E6JZKEPG5S", "status": "disabled" } ] } }, "required": [ "customerId", "paymentMethodType", "fiatPaymentInstructions" ] } }, "required": [ "account" ] } ] }, "SellAndPayRequest": { "type": "object", "required": [ "customerId", "externalRef", "qrCode", "paymentCurrency" ], "properties": { "customerId": { "type": "string", "format": "uuid", "description": "Unique identifier of the customer initiating the Sell and Pay transaction. Must be a valid customer registered in the system and associated with the account.", "example": "b6cecc1f-c90d-424b-adaa-c82b780696c1" }, "externalRef": { "type": "string", "maxLength": 250, "description": "External reference identifier for tracking purposes. This can be used to correlate the transaction with external systems or partner records.", "example": "sp-12345-2024" }, "qrCode": { "type": "string", "minLength": 1, "description": "QR code data containing the payment information for the merchant. This includes payment details such as recipient information and amount to be paid in fiat currency.", "example": "00020101021226360014BR.GOV.BCB.PIX0114+55119876543215204000053039865802BR5913Store Name XYZ6009SAO PAULO62070503***6304ABCD" }, "paymentCurrency": { "type": "string", "enum": [ "ARS", "COP" ], "description": "Fiat currency in which the payment will be made to the merchant. Must be one of the supported fiat currencies. Use `ARS` for Argentina QR payments and `COP` for Colombia BREB-QR payments.", "example": "ARS" }, "depositCurrency": { "type": "string", "maxLength": 10, "description": "Cryptocurrency that will be deposited by the customer (e.g., BTC, ETH, USDC). If not specified, the system may use default settings or require it during execution.", "example": "USDC" }, "depositNetwork": { "type": "string", "maxLength": 128, "description": "Blockchain network for the cryptocurrency deposit (e.g., ETHEREUM, POLYGON, BITCOIN). Required when depositCurrency is provided. Must be a valid network supported for the specified deposit currency.", "example": "ETHEREUM" }, "refundAddress": { "type": "string", "maxLength": 255, "description": "Cryptocurrency address to which funds should be refunded if the transaction fails or is cancelled. Should be a valid address on the deposit network.", "example": "0x4e88BBeFF059BDDF5BF90ee0816E86eDf4214b32" } } }, "SellAndPayUpdateRequest": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+(\\.\\d{1,8})?$", "description": "Updated payment amount in fiat currency. Must be a positive decimal number with up to 8 decimal places. This represents the amount to be paid to the merchant.", "example": "10000.50" }, "depositCurrency": { "type": "string", "maxLength": 10, "description": "Updated cryptocurrency for deposit (e.g., BTC, ETH, USDC). Changing this may affect the deposit address and exchange rate.", "example": "USDC" }, "depositNetwork": { "type": "string", "maxLength": 128, "description": "Updated blockchain network for cryptocurrency deposit (e.g., ETHEREUM, POLYGON). Must be compatible with the specified deposit currency.", "example": "POLYGON" }, "refundAddress": { "type": "string", "maxLength": 255, "description": "Updated cryptocurrency refund address. Should be a valid address on the deposit network where funds will be returned in case of transaction failure.", "example": "0x4e88BBeFF059BDDF5BF90ee0816E86eDf4214b32" } }, "description": "Request body for updating a Sell and Pay transaction. All fields are optional, allowing partial updates to the transaction details." }, "SellAndPayResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the Sell and Pay transaction assigned by the B2B Service", "example": "a3b2c1d0-1234-5678-90ab-cdef12345678" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the Sell and Pay transaction was created in ISO 8601 format", "example": "2024-01-26T12:45:00.078230Z" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction will expire if not completed in ISO 8601 format. After expiration, cryptocurrency deposits will not be processed.", "example": "2024-01-26T13:45:00.078230Z" }, "customerId": { "type": "string", "format": "uuid", "description": "Unique identifier of the customer who initiated the transaction", "example": "b6cecc1f-c90d-424b-adaa-c82b780696c1" }, "trade": { "anyOf": [ { "$ref": "#/components/schemas/SellAndPayTrade" }, { "type": "null" } ], "description": "Trade execution details. This will be null until the trade is executed and contains information about the cryptocurrency-to-fiat conversion." }, "paymentOrder": { "anyOf": [ { "$ref": "#/components/schemas/SellAndPayPaymentOrder" }, { "type": "null" } ], "description": "Payment order details for the merchant payment. Contains information about the QR code payment and merchant details." }, "amount": { "type": "string", "description": "Payment amount in fiat currency to be paid to the merchant", "example": "10000.50" }, "cryptoAmount": { "type": "string", "description": "Amount of cryptocurrency required to complete the payment, calculated based on current exchange rates and fees", "example": "10.25" }, "paymentCurrency": { "type": "string", "description": "Fiat currency code for the payment (e.g., ARS, MXN, USD)", "example": "ARS" }, "depositCurrency": { "type": "string", "description": "Cryptocurrency code for the deposit (e.g., BTC, ETH, USDC)", "example": "USDC" }, "depositNetwork": { "type": "string", "description": "Blockchain network identifier for the cryptocurrency deposit (e.g., ETHEREUM, POLYGON, BITCOIN)", "example": "ETHEREUM" }, "depositAddress": { "type": "string", "description": "Cryptocurrency address where the customer should send the deposit. This is a unique address generated for this transaction.", "example": "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D" }, "cryptoDeposit": { "anyOf": [ { "$ref": "#/components/schemas/SellAndPayCryptoDeposit" }, { "type": "null" } ], "description": "Information about the cryptocurrency deposit made by the customer. This will be null until a deposit is detected on the blockchain." }, "status": { "type": "string", "enum": [ "INCOMPLETE", "PENDING", "WAITING_DEPOSIT", "RECEIVED_DEPOSIT", "CONFIRMED_DEPOSIT", "TRADE_COMPLETED", "QR_EXECUTION_PENDING", "COMPLETED", "CANCELED", "REFUND_PENDING", "REFUNDED" ], "description": "Current status of the Sell and Pay transaction. INCOMPLETE: missing required fields. PENDING: ready to execute. WAITING_DEPOSIT: executed and ready to receive crypto deposit. RECEIVED_DEPOSIT: crypto deposit detected on blockchain. CONFIRMED_DEPOSIT: crypto deposit confirmed. TRADE_COMPLETED: cryptocurrency successfully converted to fiat. QR_EXECUTION_PENDING: preparing payment to merchant. COMPLETED: payment successfully made to merchant. CANCELED: transaction cancelled. REFUND_PENDING: refund being processed. REFUNDED: funds refunded to customer.", "example": "PENDING" }, "refundAddress": { "type": [ "string", "null" ], "description": "Cryptocurrency address for refunds in case of transaction failure or cancellation" }, "refundTxnHash": { "type": [ "string", "null" ], "description": "Transaction hash for the refund transaction on the blockchain. Present when a refund has been processed.", "example": "0xdef789abc456..." } } }, "SellAndPayTrade": { "type": "object", "description": "Details of the cryptocurrency-to-fiat trade execution", "properties": { "id": { "type": "string", "description": "Unique identifier for the trade" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the trade was executed" }, "externalRef": { "type": "string", "description": "External reference from the original transaction request" }, "customerId": { "type": "string", "description": "Customer identifier (end user) for the trade" }, "quoteId": { "type": "string", "description": "Identifier of the quote used for this trade" }, "txnId": { "type": "string", "description": "Transaction identifier from the B2B Service" }, "baseAsset": { "type": "string", "description": "Base asset in the trade pair (cryptocurrency)" }, "quoteAsset": { "type": "string", "description": "Quote asset in the trade pair (fiat currency)" }, "baseAmount": { "type": "string", "description": "Amount of base asset (cryptocurrency) used in the trade" }, "quoteAmount": { "type": "string", "description": "Amount of quote asset (fiat currency) received from the trade" }, "rate": { "type": "string", "description": "Exchange rate applied to the trade including all fees and spreads" }, "marketRate": { "type": "string", "description": "Market exchange rate at the time of trade execution" }, "chargedFee": { "type": "string", "description": "Total fee charged for the trade in fiat currency" }, "cryptoChargedFee": { "type": "string", "description": "Fee charged in cryptocurrency" }, "deferredChargedFee": { "type": "string", "description": "Deferred fee amount that may be charged later" }, "feeChargedInFiat": { "type": "string", "description": "Total fee amount charged in fiat currency" } } }, "SellAndPayPaymentOrder": { "type": "object", "description": "Details of the payment order to the merchant", "properties": { "id": { "type": "string", "description": "Unique identifier for the payment order" }, "customerId": { "type": "string", "description": "Customer identifier (end user) making the payment" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the payment order was created" }, "merchant": { "type": "string", "description": "Merchant identifier or name receiving the payment" }, "qrCode": { "type": "string", "description": "Original QR code data containing payment information" }, "amount": { "type": "string", "description": "Payment amount in fiat currency" }, "currency": { "type": "string", "description": "Fiat currency code for the payment" }, "providerTxnId": { "type": [ "string", "null" ], "description": "Transaction identifier from the payment provider. Will be null until the payment is processed." } } }, "SellAndPayCryptoDeposit": { "type": "object", "description": "Information about the cryptocurrency deposit received from the customer", "properties": { "id": { "type": "string", "description": "Unique identifier for the crypto deposit record" }, "txnId": { "type": "string", "description": "Transaction identifier in the B2B Service" }, "hash": { "type": "string", "description": "Blockchain transaction hash for the deposit" }, "currencyCode": { "type": "string", "description": "Cryptocurrency code of the deposited asset (e.g., BTC, ETH)" }, "addressDestination": { "type": "string", "description": "Destination address that received the cryptocurrency deposit" }, "confirmationDate": { "type": "string", "format": "date-time", "description": "Timestamp when the deposit was confirmed on the blockchain" }, "amount": { "type": "string", "description": "Amount of cryptocurrency deposited" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the deposit record was created" }, "customerId": { "type": "string", "description": "Customer identifier (end user) who made the deposit" }, "status": { "type": "string", "description": "Status of the crypto deposit (e.g., PENDING, CONFIRMED, PROCESSING)" }, "network": { "type": "string", "description": "Blockchain network where the deposit was made (e.g., ETHEREUM, POLYGON)" } } }, "ValidateQrCodeRequest": { "type": "object", "required": [ "qrCode" ], "properties": { "qrCode": { "type": "string", "minLength": 1, "description": "QR code data to validate. This contains the payment information that will be validated.", "example": "test_qr_code" } } }, "ValidateQrCodeResponse": { "type": "object", "properties": { "merchantName": { "type": "string", "description": "Name of the merchant associated with the QR code.", "example": "Test Merchant" } } }, "TermsAndConditionsResponse": { "type": "object", "properties": { "termsId": { "type": "string", "format": "uuid", "description": "Unique identifier for the Terms and Conditions.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "country": { "type": "string", "description": "Country code these Terms and Conditions apply to.", "example": "AR" }, "version": { "type": "string", "description": "Version string of the Terms and Conditions.", "example": "1.0" }, "url": { "type": "string", "format": "uri", "description": "URL where the full Terms and Conditions document can be read.", "example": "https://example.com/terms/v1.0" } }, "required": [ "termsId", "country", "version", "url" ] }, "AcceptTermsRequest": { "type": "object", "properties": { "termsId": { "type": "string", "format": "uuid", "description": "UUID of the Terms and Conditions the customer is accepting.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "ipAddress": { "type": "string", "format": "ipv4", "description": "IP address of the customer at the time of acceptance.", "example": "192.168.1.100" }, "userAgent": { "type": "string", "description": "User agent string from the customer's browser or app (optional).", "example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" } }, "required": [ "termsId", "ipAddress" ] }, "CustomerTermsAcceptanceResponse": { "type": "object", "properties": { "termsId": { "type": "string", "format": "uuid", "description": "UUID of the accepted Terms and Conditions.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "ipAddress": { "type": "string", "description": "IP address recorded at the time of acceptance.", "example": "192.168.1.100" }, "userAgent": { "type": [ "string", "null" ], "description": "User agent recorded at the time of acceptance. Returns `null` if not provided in the request.", "example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" }, "acceptedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the customer accepted the Terms and Conditions.", "example": "2024-06-01T12:00:00Z" } }, "required": [ "termsId", "ipAddress", "acceptedAt" ] }, "Milestone": { "type": "object", "description": "Status and timestamp of a single step in a transaction timeline.", "properties": { "status": { "type": "string", "description": "Current status of this milestone.", "enum": [ "not_started", "in_progress", "completed", "failed" ] }, "at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp when this milestone was reached. Null if not yet reached." } }, "required": [ "status", "at" ] }, "OnRampTransactionTimeline": { "type": "object", "description": "Progress milestones for an on-ramp transaction.", "properties": { "paymentReceived": { "$ref": "#/components/schemas/Milestone" }, "cryptoSent": { "$ref": "#/components/schemas/Milestone" }, "cryptoDelivered": { "$ref": "#/components/schemas/Milestone" } }, "required": [ "paymentReceived", "cryptoSent", "cryptoDelivered" ] }, "OffRampTransactionTimeline": { "type": "object", "description": "Progress milestones for an off-ramp transaction.", "properties": { "cryptoReceived": { "$ref": "#/components/schemas/Milestone" }, "fundsSent": { "$ref": "#/components/schemas/Milestone" }, "fundsConfirmed": { "$ref": "#/components/schemas/Milestone" } }, "required": [ "cryptoReceived", "fundsSent", "fundsConfirmed" ] }, "OnRampTransactionDestination": { "type": "object", "description": "Crypto destination address for an on-ramp transaction.", "properties": { "kind": { "type": "string", "description": "Type of destination.", "enum": [ "ADDRESS" ] }, "value": { "type": "string", "description": "The crypto wallet address." }, "label": { "type": [ "string", "null" ], "description": "Optional human-readable label for the address." } }, "required": [ "kind", "value", "label" ] }, "OffRampTransactionDestination": { "type": "object", "description": "Fiat destination account for an off-ramp transaction.", "properties": { "kind": { "type": "string", "description": "Type of fiat destination identifier.", "enum": [ "CVU", "ALIAS", "CLABE", "BREB_KEY" ] }, "value": { "type": "string", "description": "The fiat account identifier (CVU number, alias, CLABE, or BREB key)." }, "label": { "type": [ "string", "null" ], "description": "Optional human-readable label for the destination." } }, "required": [ "kind", "value", "label" ] }, "PublicFailureReason": { "type": "string", "description": "Sanitized reason for a failed or cancelled transaction, suitable for display to end customers. Only populated for `CANCELLED`, `REFUNDED`, or `PENDING` (when a correctable error is present) states. `INVALID_DESTINATION` means the customer's fiat account details have a problem they can fix. `EXPIRED_QUOTE` means the quote expired before execution. `PROVIDER_REJECTED` means a provider business rule blocked the transaction. `PROVIDER_ERROR` means a transient provider issue. `REFUND_BY_PROVIDER` means the provider initiated a refund. `USER_BANNED` means the customer is banned. `INTERNAL_ERROR` is a catch-all for other failures.", "enum": [ "INVALID_DESTINATION", "EXPIRED_QUOTE", "PROVIDER_REJECTED", "PROVIDER_ERROR", "REFUND_BY_PROVIDER", "USER_BANNED", "INTERNAL_ERROR" ] }, "CustomerOnRampTransactionItem": { "type": "object", "description": "An on-ramp transaction in the customer's transaction history.", "properties": { "transactionId": { "type": "string", "format": "uuid", "description": "Unique identifier for the transaction.", "example": "21d8a046-3221-4b43-a301-0f9adcdd9a45" }, "type": { "type": "string", "description": "Transaction type.", "enum": [ "ONRAMP" ], "example": "ONRAMP" }, "status": { "type": "string", "description": "Public-facing transaction status. `PENDING_MANUAL_RETRY` is exposed as `PENDING`.", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "CANCELLED", "REFUNDED" ], "example": "COMPLETED" }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time the transaction was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Date and time the transaction was last updated." }, "fromAmount": { "type": "string", "description": "Amount of fiat currency sent by the customer.", "example": "1000.00" }, "toAmount": { "type": "string", "description": "Amount of cryptocurrency received.", "example": "1.23456789" }, "exchangeRate": { "type": "string", "description": "Effective exchange rate applied (executed rate if available, otherwise quoted rate).", "example": "812.345" }, "fromCurrency": { "type": "string", "description": "Fiat currency used.", "example": "ARS" }, "toCurrency": { "type": "string", "description": "Cryptocurrency received.", "example": "USDC" }, "chain": { "type": "string", "description": "Blockchain network used for the crypto delivery.", "example": "POLYGON" }, "txnHash": { "type": [ "string", "null" ], "description": "On-chain transaction hash. Null if not yet processed.", "example": null }, "paymentMethodType": { "type": "string", "description": "Payment method used for the fiat deposit.", "example": "bank_transfer" }, "metadata": { "type": "object", "description": "Additional metadata associated with the transaction.", "additionalProperties": true, "example": {} }, "failureReason": { "oneOf": [ { "$ref": "#/components/schemas/PublicFailureReason" }, { "type": "null" } ], "description": "Reason for failure or cancellation. Null when not applicable." }, "destination": { "$ref": "#/components/schemas/OnRampTransactionDestination" }, "timeline": { "$ref": "#/components/schemas/OnRampTransactionTimeline" } }, "required": [ "transactionId", "type", "status", "createdAt", "updatedAt", "fromAmount", "toAmount", "exchangeRate", "fromCurrency", "toCurrency", "chain", "txnHash", "paymentMethodType", "metadata", "failureReason", "destination", "timeline" ] }, "CustomerOffRampTransactionItem": { "type": "object", "description": "An off-ramp transaction in the customer's transaction history.", "properties": { "transactionId": { "type": "string", "format": "uuid", "description": "Unique identifier for the transaction.", "example": "8a3c1e2f-7b4d-4c5e-a6f7-0d1e2f3a4b5c" }, "type": { "type": "string", "description": "Transaction type.", "enum": [ "OFFRAMP" ], "example": "OFFRAMP" }, "status": { "type": "string", "description": "Public-facing transaction status.", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "CANCELLED", "REFUNDED" ], "example": "COMPLETED" }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time the transaction was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Date and time the transaction was last updated." }, "fromAmount": { "type": "string", "description": "Amount of cryptocurrency sent by the customer.", "example": "1.23456789" }, "toAmount": { "type": "string", "description": "Amount of fiat currency to be received.", "example": "1000.00" }, "exchangeRate": { "type": "string", "description": "Effective exchange rate applied.", "example": "812.345" }, "fromCurrency": { "type": "string", "description": "Cryptocurrency sent.", "example": "USDC" }, "toCurrency": { "type": "string", "description": "Fiat currency to be received.", "example": "ARS" }, "chain": { "type": "string", "description": "Blockchain network from which the crypto was sent.", "example": "POLYGON" }, "txnHash": { "type": [ "string", "null" ], "description": "On-chain transaction hash of the incoming crypto deposit.", "example": null }, "paymentMethodType": { "type": "string", "description": "Payment method used for the fiat payout.", "example": "bank_transfer" }, "metadata": { "type": "object", "description": "Additional metadata associated with the transaction.", "additionalProperties": true, "example": {} }, "failureReason": { "oneOf": [ { "$ref": "#/components/schemas/PublicFailureReason" }, { "type": "null" } ], "description": "Reason for failure or cancellation. Null when not applicable." }, "destination": { "oneOf": [ { "$ref": "#/components/schemas/OffRampTransactionDestination" }, { "type": "null" } ], "description": "Fiat account destination. Null when no fiat account is associated." }, "fiatAccountId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the customer's fiat account used as destination. Null if not set.", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "fiatAccountStatus": { "type": [ "string", "null" ], "description": "Current status of the destination fiat account. Null if not set.", "example": "ACTIVE" }, "providerId": { "type": [ "string", "null" ], "description": "Transaction ID assigned by the fiat payout provider. Null until the provider confirms.", "example": "cobre-txn-9876" }, "timeline": { "$ref": "#/components/schemas/OffRampTransactionTimeline" } }, "required": [ "transactionId", "type", "status", "createdAt", "updatedAt", "fromAmount", "toAmount", "exchangeRate", "fromCurrency", "toCurrency", "chain", "txnHash", "paymentMethodType", "metadata", "failureReason", "destination", "fiatAccountId", "fiatAccountStatus", "providerId", "timeline" ] }, "PaginatedCustomerOnRampTransactionList": { "type": "object", "description": "Paginated list of a customer's on-ramp transactions.", "properties": { "count": { "type": "integer", "description": "Total number of transactions across all pages." }, "next": { "type": [ "string", "null" ], "format": "uri", "description": "URL to the next page of results. Null if no next page." }, "previous": { "type": [ "string", "null" ], "format": "uri", "description": "URL to the previous page of results. Null if no previous page." }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerOnRampTransactionItem" }, "description": "Array of on-ramp transactions for the current page." } }, "required": [ "count", "next", "previous", "transactions" ] }, "PaginatedCustomerOffRampTransactionList": { "type": "object", "description": "Paginated list of a customer's off-ramp transactions.", "properties": { "count": { "type": "integer", "description": "Total number of transactions across all pages." }, "next": { "type": [ "string", "null" ], "format": "uri", "description": "URL to the next page of results. Null if no next page." }, "previous": { "type": [ "string", "null" ], "format": "uri", "description": "URL to the previous page of results. Null if no previous page." }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerOffRampTransactionItem" }, "description": "Array of off-ramp transactions for the current page." } }, "required": [ "count", "next", "previous", "transactions" ] }, "TermsAcceptanceStatusResponse": { "type": "object", "properties": { "termsId": { "type": [ "string", "null" ], "format": "uuid", "description": "UUID of the active Terms and Conditions. `null` when no active T&C exist for the country.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "country": { "type": "string", "description": "Country code these Terms and Conditions apply to.", "example": "AR" }, "version": { "type": [ "string", "null" ], "description": "Version string of the active Terms and Conditions. `null` when no active T&C exist.", "example": "1.0" }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "URL where the full Terms and Conditions document can be read. `null` when no active T&C exist.", "example": "https://example.com/terms/v1.0" }, "accepted": { "type": "boolean", "description": "Whether the customer has accepted the currently active Terms and Conditions. Always `true` when no active T&C exist for the country (the customer is not blocked).", "example": true }, "acceptedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the customer last accepted the active Terms and Conditions. `null` if not yet accepted.", "example": "2024-06-01T12:00:00Z" } }, "required": [ "country", "accepted" ] } }, "parameters": { "CustomerId": { "name": "customerId", "in": "path", "required": true, "description": "Unique identifier for the customer.", "schema": { "type": "string", "format": "uuid" }, "example": "8142b065-79c4-4f48-9e33-11b17bc658d4" }, "SessionId": { "name": "sessionId", "in": "path", "required": true, "description": "Unique identifier for the session.", "schema": { "type": "string", "format": "uuid" }, "example": "fca6d32f-2f7e-4f7e-b224-8be0b92fa3f1" }, "StartDate": { "name": "startDate", "in": "query", "description": "Filter orders/sessions created after this date (ISO 8601 format).", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2024-01-26T12:45:00.078230Z" }, "EndDate": { "name": "endDate", "in": "query", "description": "Filter orders/sessions created before this date (ISO 8601 format).", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2024-01-26T12:45:00.078230Z" }, "Limit": { "name": "limit", "in": "query", "description": "Maximum number of items to return.", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 100 }, "example": 100 }, "Offset": { "name": "offset", "in": "query", "description": "Starting point to limit the total items to return (for pagination).", "required": false, "schema": { "type": "integer", "minimum": 0 }, "example": 0 } } }, "security": [ { "BearerToken": [] } ], "paths": { "/api/v1/supportTickets/": { "post": { "summary": "Create Support Ticket", "description": "Raises a support ticket on behalf of one of your customers and queues it for Ripio's support team.\n\n**This endpoint must be enabled for your account by the Ripio team before it can be used.** It is disabled by default; while disabled, every request returns `403` with the error code `20061`. Contact Ripio to have support tickets enabled for your account.\n\nThe request is `multipart/form-data` and may include file attachments. The ticket is processed asynchronously: the endpoint responds immediately with `202 Accepted` and a `ticketId`, with `status` set to `PENDING` and `issueKey` set to `null`. The ticket reference (`issueKey`) becomes available once processing finishes. We recommend subscribing to the [Support Ticket webhook events](/ramps-api/webhooks/support-ticket-events) to be notified automatically when this happens. You can also look up a specific ticket on demand via the [Retrieve Support Ticket](/ramps-api/support-tickets/retrieve-support-ticket) endpoint.\n\nThe referenced customer must exist and have an email address on file.", "operationId": "createSupportTicket", "tags": [ "Support Tickets" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateSupportTicketRequest" }, "encoding": { "files": { "style": "form", "explode": true } } } } }, "responses": { "202": { "description": "Ticket accepted and queued for processing. `status` is `PENDING` and `issueKey` is `null` until processing completes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportTicketResponse" }, "example": { "ticketId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "status": "PENDING", "issueKey": null } } } }, "400": { "description": "Bad Request - validation error (e.g. missing required field, unknown customer, or attachments that exceed the allowed count/size/extension).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "tooManyFiles": { "summary": "Too many attachments", "value": { "code": 20000, "type": "ValidationError", "detail": { "files": [ "A maximum of 5 files is allowed per request." ] }, "status": 400 } }, "unknownCustomer": { "summary": "Customer does not exist", "value": { "code": 20000, "type": "ValidationError", "detail": { "customerId": [ "Customer does not exist." ] }, "status": 400 } }, "customerWithoutEmail": { "summary": "Customer has no email", "value": { "code": 20014, "type": "EmailRequiredException", "detail": { "message": "The customer must have an email setup." }, "status": 400 } } } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "403": { "description": "Forbidden - support tickets are not enabled for your account. Contact the Ripio team to enable this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 20061, "type": "SupportTicketsNotEnabledException", "detail": { "message": "Support tickets are not enabled for this account." }, "status": 403 } } } } } } }, "/api/v1/supportTickets/{ticketId}/": { "get": { "summary": "Retrieve Support Ticket", "description": "Returns the current status of a support ticket previously created via [Create Support Ticket](/ramps-api/support-tickets/create-support-ticket). The ticket reference (`issueKey`) becomes available once the ticket reaches the `CREATED` status.\n\nTo be notified automatically when a ticket is resolved, subscribe to the [Support Ticket webhook events](/ramps-api/webhooks/support-ticket-events). You can also check a specific ticket on demand with this endpoint.\n\n**This endpoint must be enabled for your account by the Ripio team.** While support tickets are disabled, requests return `403` with the error code `20061`.", "operationId": "retrieveSupportTicket", "tags": [ "Support Tickets" ], "parameters": [ { "name": "ticketId", "in": "path", "required": true, "description": "The `ticketId` returned by the Create Support Ticket endpoint.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current state of the support ticket.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportTicketResponse" }, "example": { "ticketId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "status": "CREATED", "issueKey": "SUP-1234" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "403": { "description": "Forbidden - support tickets are not enabled for your account. Contact the Ripio team to enable this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 20061, "type": "SupportTicketsNotEnabledException", "detail": { "message": "Support tickets are not enabled for this account." }, "status": 403 } } } }, "404": { "description": "Not Found - no support ticket with the given `ticketId` exists for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40017, "type": "SupportTicketNotFoundException", "detail": { "message": "Support ticket not found." }, "status": 404 } } } } } } }, "/oauth2/token/": { "post": { "summary": "Acquire Access Token", "description": "Every call to the API has to be authenticated with an OAuth2 Token. In order to request this token, you will need to have sandbox or production API Keys (`client_id` and `client_secret`) that will allow to negotiate an ephemeral access token.\n\nTo generate the access token, you should call this endpoint providing the header `Authorization` with the following schema: `Basic CREDENTIAL` where `CREDENTIAL` should be specified as a string with the format`client_id:client_secret` encoded in Base64.", "operationId": "acquireAccessToken", "tags": [ "Authentication" ], "security": [ { "BasicAuth": [] } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "description": "Must be 'client_credentials'", "enum": [ "client_credentials" ] } }, "required": [ "grant_type" ] } } } }, "responses": { "200": { "description": "Access token granted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessTokenResponse" } } } }, "400": { "description": "Bad Request - e.g., missing grant_type or invalid credentials format.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": { "error": "unsupported_grant_type" } } } }, "401": { "description": "Unauthorized - Invalid client credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": { "error": "invalid_client" } } } } } } }, "/api/v1/customers/": { "post": { "summary": "Create Customer", "description": "Creates a new customer account (individual or business). This is the foundational step for other API use cases.", "operationId": "createCustomer", "tags": [ "Customers" ], "requestBody": { "required": true, "description": "Customer creation payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreationRequest" } } } }, "responses": { "201": { "description": "Customer created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "400": { "description": "Bad Request - e.g., invalid input data, missing required fields, or customerId already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } } } } }, "/api/v1/customers/{customerId}/": { "put": { "summary": "Update Customer", "description": "Updates an existing customer's information. Currently, only the email address can be updated.", "operationId": "updateCustomer", "tags": [ "Customers" ], "parameters": [ { "$ref": "#/components/parameters/CustomerId" } ], "requestBody": { "required": true, "description": "Customer update payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUpdateRequest" } } } }, "responses": { "200": { "description": "Customer updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "404": { "description": "Not Found - Customer not found or inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40004, "type": "NotFound", "detail": { "message": "Not found.", "code": "not_found" }, "status": 404 } } } } } } }, "/api/v1/customers/{customerId}/checkKyc/": { "post": { "summary": "Check KYC Status & Send OTP", "description": "Checks the customer's KYC status with Ripio to determine if they can be fast-tracked through onboarding.\n\n- **If the customer has a previously approved KYC with Ripio**, this endpoint sends a One-Time Password (OTP) to their email. You can then use the `POST /customers/{customerId}/otp/` endpoint to validate the OTP and instantly approve the customer's KYC with your service, skipping the full data submission process.\n\n- **If the customer's KYC is not approved with Ripio** (indicated by a `KycNotApprovedException`), you must guide them through the standard KYC process. This involves retrieving the required fields via `GET /kycRequirements/` and submitting their data using `POST /customers/{customerId}/kyc/`.\n\n- **If the customer's KYC has already been approved with your service**, a `KycAlreadyApprovedException` will be returned.", "operationId": "checkKycAndSendOtp", "tags": [ "KYC" ], "parameters": [ { "$ref": "#/components/parameters/CustomerId" } ], "responses": { "200": { "description": "KYC approved in Ripio and OTP sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KycCheckSuccessResponse" } } } }, "400": { "description": "Bad Request - e.g., KYC already approved by partner, KYC not approved in Ripio, or other validation errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "kycAlreadyApproved": { "summary": "KYC already approved by partner", "value": { "code": 20015, "type": "KycAlreadyApprovedException", "detail": { "message": "KYC for customer '660c406c-918e-494d-acec-049758a0b413 - individual@mail.com' is approved." }, "status": 400 } }, "kycNotApprovedInRipio": { "summary": "KYC not approved in Ripio", "value": { "code": 20007, "type": "KycNotApprovedException", "detail": { "message": "KYC for customer '0ff137ac-3ef5-464d-b6c5-a6aac8f75843 - individual@mail.com' is not approved." }, "status": 400 } } } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "404": { "description": "Not Found - Customer not found or inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40004, "type": "NotFound", "detail": { "message": "Not found.", "code": "not_found" }, "status": 404 } } } } } } }, "/api/v1/customers/{customerId}/otp/": { "post": { "summary": "Validate OTP for KYC Reuse", "description": "Receives the OTP sent to the customer's email. If the OTP is valid, an approved KYC is created for the customer.", "operationId": "validateKycOtp", "tags": [ "KYC" ], "parameters": [ { "$ref": "#/components/parameters/CustomerId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KycOtpValidationRequest" } } } }, "responses": { "200": { "description": "OTP valid and KYC created successfully. Empty body." }, "400": { "description": "Bad Request - e.g., Invalid OTP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidOtp": { "summary": "Invalid OTP", "value": { "code": 20013, "type": "InvalidOtpException", "detail": { "message": "Invalid otp '123456'." }, "status": 400 } } } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "404": { "description": "Not Found - Customer not found or inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40004, "type": "NotFound", "detail": { "message": "Not found.", "code": "not_found" }, "status": 404 } } } } } } }, "/api/v1/kycRequirements/": { "get": { "summary": "Retrieve KYC Requirements", "description": "Retrieves the specific Know Your Customer (KYC) requirements, detailing the fields and document types needed for customer verification.", "operationId": "getKycRequirements", "tags": [ "KYC" ], "responses": { "200": { "description": "Successfully retrieved KYC requirements.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KycRequirementsResponse" }, "example": { "kycRequiredFields": [ { "fieldName": "legalFirstName", "required": true, "type": "TEXT" }, { "fieldName": "legalLastName", "required": true, "type": "TEXT" }, { "fieldName": "dateOfBirth", "required": true, "type": "DATE" }, { "fieldName": "idNumber", "required": true, "type": "TEXT" }, { "fieldName": "nationality", "required": true, "type": "TEXT", "choices": [ { "value": "AR", "label": "Argentina" }, { "value": "BR", "label": "Brazil" }, { "value": "CO", "label": "Colombia" } ] } ] } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } } } } }, "/api/v1/customers/{customerId}/kyc/": { "post": { "summary": "Submit KYC Information", "description": "Submits KYC data for a specific customer. The response will include a URL to a third-party KYC provider's widget for document uploads and liveness checks. Webhook events will notify about the validation process.\n\n The provider URL for document uploads and liveness checks only works in production.", "operationId": "submitKycInformation", "tags": [ "KYC" ], "parameters": [ { "$ref": "#/components/parameters/CustomerId" } ], "requestBody": { "required": true, "description": "KYC data for the customer. Structure should align with fields from /kycRequirements/.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KycSubmissionRequest" }, "examples": { "Argentina": { "summary": "Argentina KYC Submission (API flow)", "value": { "kycSubmission": { "country": "AR", "first_name": "Mateo", "last_name": "Romero", "gender": "M", "birthday": "1990-01-25", "nationality": "AR", "id_number_type": "DNI", "id_number": "11122233", "registered_tax_payer": false, "cuit": "20111222330", "address": "Libertad", "address_flat": "1", "address_number": "333", "postal_code": "1012", "district": "Chubut", "city": "Trelew", "state": "AR.CH", "phone": "+542211228855", "personal_activity": "AR.6" }, "redirectUrl": "https://www.example.com/" } }, "Mexico": { "summary": "Mexico KYC Submission (API flow)", "value": { "kycSubmission": { "country": "MX", "first_name": "Jose", "last_name": "Lopez", "gender": "H", "birthday": "1995-11-19", "birthday_place": "Guadalajara", "nationality": "MX", "id_number_type": "CURP", "id_number": "LOXJ951119HJCPXS09", "date_of_issue": "2024-01-01", "date_of_expiration": "2034-01-01", "rfc": "LOJO951119Q18", "address": "isla cartagena", "address_flat": "1", "address_number": "1505", "postal_code": "44950", "district": "district", "city": "Guadalajara", "state": "MX.JA", "phone": "+523325606411", "net_income": "10000", "personal_activity": "MX.1000000", "terms_conditions": true, "address_photo": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..." } } }, "RipioKyc": { "summary": "Ripio KYC delegated flow", "description": "Used when the account is configured for the Ripio KYC delegated flow. KYC data is not collected directly \u2014 the user is redirected to Ripio's KYC platform to complete the process.", "value": { "redirectUrl": "https://www.example.com/" } }, "Colombia": { "summary": "Colombia KYC Submission", "value": { "country": "CO", "first_name": "Santiago", "last_name": "Garc\u00eda", "birthday": "1992-05-15", "nationality": "CO", "id_number": "1234567890", "id_number_type": "CC", "address": "Carrera 7", "address_number": "45", "address_type": "HOME", "state": "CO.DC", "city": "Bogot\u00e1", "phone": "+573001234567", "district": "Chapinero" } } } } } }, "responses": { "200": { "description": "KYC submission received successfully. Includes providerUrl for document upload and liveness check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KycSubmissionResponse" } } } }, "201": { "description": "KYC submission received successfully (alternative success code, as per PDF example for other POSTs). Includes providerUrl for document upload and liveness check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KycSubmissionResponse" } } } }, "400": { "description": "Bad Request - e.g., invalid input data or validation errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "404": { "description": "Not Found - Customer not found or inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40004, "type": "NotFound", "detail": { "message": "Not found.", "code": "not_found" }, "status": 404 } } } } } } }, "/api/v1/customers/{customerId}/kycSubmissions/": { "get": { "summary": "Retrieve Latest KYC Submission", "description": "Retrieves the latest KYC submission for a specific customer, including its status and creation timestamp.", "operationId": "retrieveKycSubmission", "tags": [ "KYC" ], "parameters": [ { "$ref": "#/components/parameters/CustomerId" } ], "responses": { "200": { "description": "Latest KYC submission retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KycSubmissionDetailResponse" }, "example": { "customerId": "07918d77-ae84-42f1-b816-58a8b086a625", "status": "COMPLETED", "createdAt": "2024-06-13T18:10:55.939054Z" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "404": { "description": "Not Found - Customer not found, inactive, or no KYC submission exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40004, "type": "NotFound", "detail": { "message": "Not found.", "code": "not_found" }, "status": 404 } } } } } } }, "/api/v1/customers/{customerId}/acceptTerms/": { "post": { "summary": "Accept Terms and Conditions", "description": "Records the customer's acceptance of the active Terms and Conditions for their country. This endpoint is required when the Partner integrates Ramps via API. The customer must accept the T&C before performing on-ramp or off-ramp operations.", "operationId": "acceptTermsAndConditions", "tags": [ "Customers" ], "parameters": [ { "$ref": "#/components/parameters/CustomerId" } ], "requestBody": { "required": true, "description": "Terms and Conditions acceptance payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptTermsRequest" }, "example": { "termsId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "ipAddress": "192.168.1.100", "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" } } } }, "responses": { "201": { "description": "Terms and Conditions accepted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerTermsAcceptanceResponse" }, "example": { "termsId": "94b302e4-77d4-4627-af36-8265121bef29", "ipAddress": "1.1.1.1", "userAgent": null, "acceptedAt": "2026-02-25T20:29:11.243033Z" } } } }, "400": { "description": "Bad Request - Invalid input data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 20000, "type": "ValidationError", "detail": { "ipAddress": [ { "message": "Enter a valid IPv4 or IPv6 address.", "code": "invalid" } ] }, "status": 400 } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "404": { "description": "Not Found - Customer not found or inactive, or Terms and Conditions not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CustomerNotFound": { "summary": "Customer not found", "value": { "code": 20001, "type": "CustomerNotFoundException", "detail": { "message": "Customer not found." }, "status": 404 } }, "TermsNotFound": { "summary": "Terms and Conditions not found", "value": { "code": 20040, "type": "TermsAndConditionsNotFoundException", "detail": { "message": "No active Terms and Conditions found for this id and country." }, "status": 404 } } } } } } } } }, "/api/v1/customers/{customerId}/fiatAccount/": { "post": { "summary": "Create Deposit Account", "description": "Creates the customer's deposit account on demand, prior to the on-ramp flow. If the provider does not require prior account creation, returns `200 OK` with no side effects. The customer must have an approved KYC before calling this endpoint.", "operationId": "createDepositAccount", "tags": [ "Customers" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "description": "Unique identifier of the customer.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "description": "Payment method type for the deposit account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDepositAccountRequest" } } } }, "responses": { "201": { "description": "Deposit account created successfully.", "content": { "application/json": { "schema": { "type": "object", "example": {} } } } }, "200": { "description": "Provider does not require prior account creation. No action was taken.", "content": { "application/json": { "schema": { "type": "object", "example": {} } } } }, "400": { "description": "Bad Request - e.g., KYC not approved or missing required fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "kycNotApproved": { "summary": "KYC not approved", "value": { "code": 40010, "type": "KycNotApprovedException", "detail": { "message": "Customer KYC is not approved." }, "status": 400 } } } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "404": { "description": "Not Found - Customer not found or inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40004, "type": "NotFound", "detail": { "message": "Not found.", "code": "not_found" }, "status": 404 } } } } } } }, "/api/v1/customers/{customerId}/transactions/onramp/": { "get": { "summary": "List Customer's On-Ramp Transaction History", "description": "Returns a paginated list of on-ramp transactions for a specific customer, ordered by most recently updated. Use this endpoint to display transaction history to end customers in your widget or integration. Returns 404 if the customer does not exist or does not belong to your account.", "operationId": "listCustomerOnRampTransactions", "tags": [ "Transactions" ], "parameters": [ { "$ref": "#/components/parameters/CustomerId" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "Paginated list of the customer's on-ramp transactions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCustomerOnRampTransactionList" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "404": { "description": "Not Found - Customer not found, inactive, or does not belong to your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40004, "type": "NotFound", "detail": { "message": "Not found.", "code": "not_found" }, "status": 404 } } } } } } }, "/api/v1/customers/{customerId}/transactions/offramp/": { "get": { "summary": "List Customer's Off-Ramp Transaction History", "description": "Returns a paginated list of off-ramp transactions for a specific customer, ordered by most recently updated. Use this endpoint to display transaction history to end customers in your widget or integration. Returns 404 if the customer does not exist or does not belong to your account.", "operationId": "listCustomerOffRampTransactions", "tags": [ "Transactions" ], "parameters": [ { "$ref": "#/components/parameters/CustomerId" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "Paginated list of the customer's off-ramp transactions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCustomerOffRampTransactionList" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "404": { "description": "Not Found - Customer not found, inactive, or does not belong to your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40004, "type": "NotFound", "detail": { "message": "Not found.", "code": "not_found" }, "status": 404 } } } } } } }, "/api/v1/customers/{customerId}/deactivate/": { "post": { "summary": "Deactivate Customer", "description": "Deactivates a customer account and all associated fiat accounts. This action sets the customer and their deposit accounts to inactive. External fiat accounts are transitioned to deactivated as well.", "operationId": "deactivateCustomer", "tags": [ "Customers" ], "parameters": [ { "$ref": "#/components/parameters/CustomerId" } ], "responses": { "200": { "description": "Customer deactivated successfully.", "content": { "application/json": { "schema": { "type": "object", "example": {} } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "404": { "description": "Not Found - Customer not found or inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40004, "type": "NotFound", "detail": { "message": "Not found.", "code": "not_found" }, "status": 404 } } } } } } }, "/api/v1/termsAndConditions/": { "get": { "summary": "Get Terms and Conditions", "description": "Returns the currently active Terms and Conditions for the account's country. Use the `termsId` from the response when calling `POST /api/v1/customers/{customerId}/acceptTerms/`.", "operationId": "getTermsAndConditions", "tags": [ "Terms and Conditions" ], "responses": { "200": { "description": "Active Terms and Conditions retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsAndConditionsResponse" }, "example": { "termsId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "country": "AR", "version": "1.0", "url": "https://example.com/terms/v1.0" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } } } } }, "/api/v1/fiatAccounts/": { "post": { "summary": "Create Fiat Account", "description": "Creates a new fiat account for a customer, linked to specific bank or virtual wallet details for withdrawals.\n\n**Argentina** and **Colombia** (BRE-B payment method): Fiat accounts are created with `UNCONFIRMED` status. The response includes pre-validation `metadata` (e.g., CVU holder information) for the end-user to review. You must call the [Confirm Fiat Account](/ramps-api/fiat-accounts/confirm-fiat-account) endpoint to start the enabling process.\n\n**Important for Mexico**: For off-ramp operations in Mexico, both the owner name and RFC registered in the customer's KYC information must match the bank account owner's name and RFC. This is a regulatory requirement.", "operationId": "createFiatAccount", "tags": [ "Fiat Accounts" ], "requestBody": { "required": true, "description": "Details for the new fiat account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiatAccountCreationRequest" }, "examples": { "Argentina": { "summary": "Argentina - CBU/CVU/Alias Account", "value": { "customerId": "964c8c8c-573d-4f8f-bd2e-8645c3124e74", "paymentMethodType": "bank_transfer", "accountFields": { "alias_or_cvu_destination": "0100000000000000000001" } } }, "Mexico": { "summary": "Mexico - CLABE Account", "description": "For Mexico, the owner name and RFC registered in KYC must match the bank account owner's name and RFC.", "value": { "customerId": "50277a14-2376-4e42-985e-4bc1f7303dc3", "paymentMethodType": "bank_transfer", "accountFields": { "clabe_destination": "706180196550550550" } } }, "Colombia - BREB": { "summary": "Colombia - BREB Key Account", "value": { "customerId": "a3b2c1d0-1234-5678-9abc-def012345678", "paymentMethodType": "breb", "accountFields": { "key_value": "@ABC123" } } }, "Colombia - Bank Transfer": { "summary": "Colombia - Bank Transfer Account", "description": "For Colombia bank transfers, use GET /api/v1/banks/ to retrieve valid beneficiary_institution codes and their allowed counterparty_types.", "value": { "customerId": "a3b2c1d0-1234-5678-9abc-def012345678", "paymentMethodType": "bank_transfer", "accountFields": { "counterparty_type": "cc", "counterparty_fullname": "Santiago Garc\u00eda", "counterparty_id_type": "cc", "counterparty_id_number": "1234567890", "beneficiary_institution": "1001", "account_number": "12345678901234" } } } } } } }, "responses": { "201": { "description": "Fiat account created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiatAccount" } } } }, "400": { "description": "Bad Request - e.g., invalid input data, missing required fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "404": { "description": "Not Found - Customer not found or inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40004, "type": "NotFound", "detail": { "message": "Not found.", "code": "not_found" }, "status": 404 } } } } } }, "get": { "summary": "List Fiat Accounts", "description": "Retrieves a list of fiat accounts, optionally filtered by customerId or paymentMethodType. Results are limited to active customers \u2014 fiat accounts belonging to deactivated customers are excluded.", "operationId": "listFiatAccounts", "tags": [ "Fiat Accounts" ], "parameters": [ { "name": "customerId", "in": "query", "description": "Filter fiat accounts by the customer's unique identifier.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "paymentMethodType", "in": "query", "description": "Filter fiat accounts by its type.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A paginated list of fiat accounts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedFiatAccountList" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } } } } }, "/api/v1/fiatAccounts/{fiatAccountId}/confirm/": { "post": { "summary": "Confirm Fiat Account", "description": "Confirms an unconfirmed fiat account and starts the enabling process.\n\nThis endpoint is currently only applicable for Argentina and Colombia (BRE-B payment method) fiat accounts, where accounts are created in `UNCONFIRMED` status by default.", "operationId": "confirmFiatAccount", "tags": [ "Fiat Accounts" ], "parameters": [ { "name": "fiatAccountId", "in": "path", "required": true, "description": "The unique identifier of the fiat account to confirm.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Fiat account confirmed successfully. Status is now `PROCESSING`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiatAccount" }, "example": { "fiatAccountId": "a1b2c3d4-5678-9abc-def0-123456789abc", "fiatAccountFields": { "alias_or_cvu_destination": "0100000000000000000001" }, "status": "PROCESSING", "createdAt": "2026-02-01T12:00:00Z", "customerId": "964c8c8c-573d-4f8f-bd2e-8645c3124e74", "metadata": {} } } } }, "400": { "description": "Bad Request - The fiat account is not in `UNCONFIRMED` status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40000, "type": "InvalidExternalFiatAccountStatusException", "detail": { "message": "Fiat account status is 'processing', expected 'unconfirmed'." }, "status": 400 } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "404": { "description": "Not Found - Fiat account not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40004, "type": "NotFound", "detail": { "message": "Not found.", "code": "not_found" }, "status": 404 } } } } } } }, "/api/v1/fiatAccounts/requirements/": { "get": { "summary": "Retrieve Fiat Account Requirements", "description": "Retrieves the specific payment details required for creating Fiat Accounts based on a payment method.", "operationId": "getFiatAccountRequirements", "tags": [ "Fiat Accounts" ], "parameters": [ { "name": "paymentMethod", "in": "query", "description": "The payment method for which to retrieve requirements (e.g., bank_transfer).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved fiat account requirements.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiatAccountRequirementsResponse" }, "examples": { "Argentina": { "summary": "Argentina - CVU/Alias Requirements", "value": [ { "fieldName": "alias_or_cvu_destination", "required": true, "type": "TEXT" } ] }, "Mexico": { "summary": "Mexico - CLABE Requirements", "value": [ { "fieldName": "clabe_destination", "required": true, "type": "TEXT" } ] }, "Colombia - BREB": { "summary": "Colombia - BREB Requirements", "value": [ { "fieldName": "key_value", "required": true, "type": "TEXT" } ] }, "Colombia - Bank Transfer": { "summary": "Colombia - Bank Transfer Requirements", "description": "Use GET /api/v1/banks/ to retrieve valid beneficiary_institution codes and their allowed counterparty_types.", "value": [ { "fieldName": "counterparty_type", "required": true, "type": "CHOICE", "choices": [ { "value": "cc", "label": "Cuenta corriente" }, { "value": "ch", "label": "Cuenta de ahorro" }, { "value": "dp", "label": "Dep\u00f3sito" } ] }, { "fieldName": "counterparty_fullname", "required": true, "type": "TEXT" }, { "fieldName": "counterparty_id_type", "required": true, "type": "CHOICE", "choices": [ { "value": "cc", "label": "C\u00e9dula de ciudadan\u00eda" }, { "value": "nit", "label": "NIT" }, { "value": "ce", "label": "C\u00e9dula de extranjer\u00eda" } ] }, { "fieldName": "counterparty_id_number", "required": true, "type": "TEXT" }, { "fieldName": "beneficiary_institution", "required": true, "type": "TEXT" }, { "fieldName": "account_number", "required": true, "type": "TEXT" } ] } } } } }, "400": { "description": "Bad Request - e.g., missing or invalid paymentMethod.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } } } } }, "/api/v1/banks/": { "get": { "summary": "List Bank Codes", "description": "Retrieves a list of available bank codes for creating fiat accounts via bank transfer in Colombia. Each bank includes its code (used as `beneficiary_institution` when creating a fiat account) and the allowed `counterparty_type` values.\n\nThis endpoint is only available for accounts operating in Colombia (CO). Requests from accounts in other countries will return a 400 error.", "operationId": "listBankCodes", "tags": [ "Fiat Accounts" ], "responses": { "200": { "description": "A list of available bank codes.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BankCode" } }, "example": [ { "code": "1001", "name": "Banco de Bogot\u00e1", "type": [ "cc", "ch" ], "logo": "https://example.com/logos/banco-bogota.png" }, { "code": "1002", "name": "Banco Popular", "type": [ "cc" ], "logo": "https://example.com/logos/banco-popular.png" }, { "code": "1003", "name": "Bancolombia", "type": [ "cc", "ch", "dp" ], "logo": "https://example.com/logos/bancolombia.png" } ] } } }, "400": { "description": "Bad Request - Account country is not supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "type": "UnsupportedCountryException", "detail": { "message": "Country 'MX' is not supported." }, "status": 400 } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } } } } }, "/api/v1/quotes/": { "post": { "summary": "Create Quote", "description": "Obtains a held price quote for a cryptocurrency conversion, valid for a limited time (e.g., 30 seconds). This quote includes the exchange rate and applicable fees, serving as the basis for on-ramp and off-ramp operations.", "operationId": "createQuote", "tags": [ "Quotes" ], "requestBody": { "required": true, "description": "Details for the quote request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteCreationRequest" } } } }, "responses": { "201": { "description": "Quote created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" } } } }, "400": { "description": "Bad Request - e.g., invalid currency pair, amount, or other parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } } } } }, "/api/v1/onramp/": { "post": { "summary": "Create On-Ramp Order", "description": "Initiates a fiat-to-crypto on-ramp transaction process based on a previously obtained quote. Returns transaction details and fiat payment instructions for the customer.", "operationId": "createOnRampOrder", "tags": [ "On-Ramp" ], "requestBody": { "required": true, "description": "Details for creating an on-ramp order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnRampOrderCreationRequest" } } } }, "responses": { "201": { "description": "On-Ramp order created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnRampOrderResponse" } } } }, "400": { "description": "Bad Request - e.g., invalid quoteId, customerId, or depositAddress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "404": { "description": "Not Found - e.g., Customer not found or inactive, or Quote not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40004, "type": "NotFound", "detail": { "message": "Not found.", "code": "not_found" }, "status": 404 } } } } } }, "get": { "summary": "List On-Ramp Orders", "description": "Retrieves a list of on-ramp orders, with optional filtering by date range and pagination. Results are limited to active customers \u2014 orders belonging to deactivated customers are excluded.", "operationId": "listOnRampOrders", "tags": [ "On-Ramp" ], "parameters": [ { "$ref": "#/components/parameters/StartDate" }, { "$ref": "#/components/parameters/EndDate" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "A paginated list of on-ramp orders.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedOnRampOrderList" } } } }, "400": { "description": "Bad Request - e.g., invalid filter parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } } } } }, "/api/v1/onrampSession/": { "post": { "summary": "Create On-Ramp Session", "description": "Initiates an on-ramp session for a customer, specifying payment method, chain, cryptocurrency, and deposit address. Returns session details and payment instructions.", "operationId": "createOnRampSession", "tags": [ "On-Ramp" ], "requestBody": { "required": true, "description": "Details for creating an on-ramp session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnRampSessionCreationRequest" }, "examples": { "Sandbox": { "summary": "Sandbox (RTEST on Ethereum Sepolia)", "value": { "customerId": "fca6d32f-2f7e-4f7e-b224-8be0b92fa3f1", "paymentMethodType": "bank_transfer", "chain": "ETHEREUM_SEPOLIA", "currency": "RTEST", "depositAddress": "0x866B933Aabc4F9813405C6E393dbD4B600eF3E2e" } } } } } }, "responses": { "201": { "description": "On-Ramp session created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnRampSessionResponse" } } } }, "400": { "description": "Bad Request - e.g., invalid parameters, or user already has an active session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "404": { "description": "Not Found - e.g., Customer not found or inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40004, "type": "NotFound", "detail": { "message": "Not found.", "code": "not_found" }, "status": 404 } } } } } }, "get": { "summary": "List On-Ramp Sessions", "description": "Retrieves a list of all on-ramp sessions. Results are limited to active customers \u2014 sessions belonging to deactivated customers are excluded. Pass the `customerId` query parameter to return only the session for a single customer instead of listing and filtering client-side.", "operationId": "listOnRampSessions", "tags": [ "On-Ramp" ], "parameters": [ { "name": "customerId", "in": "query", "required": false, "description": "Filter the results to the on-ramp session of a single customer, by your partner-facing customer ID.", "schema": { "type": "string", "format": "uuid" }, "example": "8142b065-79c4-4f48-9e33-11b17bc658d4" } ], "responses": { "200": { "description": "A paginated list of on-ramp sessions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedOnRampSessionList" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } } } } }, "/api/v1/onrampSession/{sessionId}/": { "get": { "summary": "Retrieve an On-Ramp Session", "description": "Retrieves the details of a specific on-ramp session by its ID.", "operationId": "getOnRampSession", "tags": [ "On-Ramp" ], "parameters": [ { "$ref": "#/components/parameters/SessionId" } ], "responses": { "200": { "description": "Details of the on-ramp session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnRampSessionResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "404": { "description": "Not Found - Session ID not found or belongs to an inactive customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40004, "type": "NotFound", "detail": { "message": "Not found.", "code": "not_found" }, "status": 404 } } } } } } }, "/api/v1/customers/{customerId}/onrampSession/": { "get": { "summary": "Retrieve a Customer's On-Ramp Session", "description": "Retrieves the on-ramp session for a specific customer, keyed by your partner-facing customer ID. A customer has at most one on-ramp session, so this returns that single session — useful for per-customer integrations that would otherwise have to list every session and filter client-side. Returns 404 if the customer does not exist, is inactive, or has no session.", "operationId": "getCustomerOnRampSession", "tags": [ "On-Ramp" ], "parameters": [ { "$ref": "#/components/parameters/CustomerId" } ], "responses": { "200": { "description": "The customer's on-ramp session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnRampSessionResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "404": { "description": "Not Found - Customer not found, inactive, or has no on-ramp session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40004, "type": "NotFound", "detail": { "message": "Not found.", "code": "not_found" }, "status": 404 } } } } } } }, "/api/v1/offrampSession/": { "post": { "summary": "Create Off-Ramp Session", "description": "Initiates an off-ramp session for a customer, specifying their fiat account. Returns session details and cryptocurrency deposit addresses.", "operationId": "createOffRampSession", "tags": [ "Off-Ramp" ], "requestBody": { "required": true, "description": "Details for creating an off-ramp session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OffRampSessionCreationRequest" } } } }, "responses": { "201": { "description": "Off-Ramp session created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OffRampSessionResponse" } } } }, "400": { "description": "Bad Request - e.g., invalid fiatAccountId, or user already has an active session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "404": { "description": "Not Found - e.g., Fiat Account not found or belongs to an inactive customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40004, "type": "NotFound", "detail": { "message": "Not found.", "code": "not_found" }, "status": 404 } } } } } }, "get": { "summary": "List Off-Ramp Sessions", "description": "Retrieves a list of all off-ramp sessions. Results are limited to active customers \u2014 sessions belonging to deactivated customers are excluded.", "operationId": "listOffRampSessions", "tags": [ "Off-Ramp" ], "responses": { "200": { "description": "A paginated list of off-ramp sessions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedOffRampSessionList" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } } } } }, "/api/v1/offrampSession/{sessionId}/": { "get": { "summary": "Retrieve an Off-Ramp Session", "description": "Retrieves the details of a specific off-ramp session by its ID.", "operationId": "getOffRampSession", "tags": [ "Off-Ramp" ], "parameters": [ { "$ref": "#/components/parameters/SessionId" } ], "responses": { "200": { "description": "Details of the off-ramp session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OffRampSessionResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "404": { "description": "Not Found - Session ID not found or belongs to an inactive customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40004, "type": "NotFound", "detail": { "message": "Not found.", "code": "not_found" }, "status": 404 } } } } } } }, "/api/v1/offramp/": { "get": { "summary": "List Off-Ramp Orders", "description": "Retrieves a list of off-ramp orders, regardless of the session, with optional filtering by date range and pagination. Results are limited to active customers \u2014 orders belonging to deactivated customers are excluded.", "operationId": "listOffRampOrders", "tags": [ "Off-Ramp" ], "parameters": [ { "$ref": "#/components/parameters/StartDate" }, { "$ref": "#/components/parameters/EndDate" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "A paginated list of off-ramp orders.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedOffRampOrderList" } } } }, "400": { "description": "Bad Request - e.g., invalid filter parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } } } } }, "/api/v1/transactionLimits/": { "get": { "summary": "Get Transaction Limits", "description": "Returns the current per-transaction limits (minimum and maximum amounts allowed for a single operation) for each enabled fiat currency and ramp operation. Amounts are expressed in the fiat currency named in each key.\n\nThese limits apply **per transaction** — there are no periodic (daily, monthly or yearly) limits in the Ramps API. Exceeding the maximum for a single On-Ramp deposit causes the transaction to be rejected and refunded (`BuyTransactionMaxLimitExceeded`, code 20018).\n\nEach key follows the pattern `{CURRENCY}_{ONRAMP|OFFRAMP}_TRANSACTION_{MIN|MAX}_LIMIT`. The set of currencies is account-dependent.", "operationId": "getTransactionLimits", "tags": [ "Transaction Limits" ], "responses": { "200": { "description": "A flat object mapping each currency/operation limit key to its amount.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionLimitsResponse" }, "example": { "ARS_ONRAMP_TRANSACTION_MIN_LIMIT": 2100, "ARS_ONRAMP_TRANSACTION_MAX_LIMIT": 500000, "ARS_OFFRAMP_TRANSACTION_MIN_LIMIT": 2121, "ARS_OFFRAMP_TRANSACTION_MAX_LIMIT": 500000, "UYU_ONRAMP_TRANSACTION_MIN_LIMIT": 0.3, "UYU_ONRAMP_TRANSACTION_MAX_LIMIT": 9999999999999, "UYU_OFFRAMP_TRANSACTION_MIN_LIMIT": 0.3, "UYU_OFFRAMP_TRANSACTION_MAX_LIMIT": 9999999999999 } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "503": { "description": "Service Unavailable - The upstream limits provider could not be reached. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 50003, "type": "ServiceUnavailable", "detail": { "message": "Service temporarily unavailable, try again later." }, "status": 503 } } } } } }, "parameters": [] }, "/api/v1/transactions/": { "get": { "summary": "List All Orders (On-Ramp & Off-Ramp)", "description": "Retrieves a unified list of all transaction orders, including both OnRamp and OffRamp types. Allows filtering by type, status, and pagination.", "operationId": "listAllTransactions", "tags": [ "Transactions" ], "parameters": [ { "name": "type", "in": "query", "description": "Filter orders by type.", "required": false, "schema": { "type": "string", "enum": [ "ONRAMP", "OFFRAMP" ] } }, { "name": "status", "in": "query", "description": "Filter orders by status.", "required": false, "schema": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "CANCELLED", "REFUNDED" ] } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "A paginated list of transactions. The structure of each object in the transactions array depends on its type (OnRamp or OffRamp).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAllOrdersList" } } } }, "400": { "description": "Bad Request - e.g., invalid filter parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } } } } }, "/api/v1/depositNetworks/": { "get": { "summary": "Get Deposit Networks", "description": "Gets the available deposit networks with their assets (currencies). Allows filtering by currency and optionally including currency details.", "operationId": "getDepositNetworks", "tags": [ "Networks" ], "parameters": [ { "name": "currency", "in": "query", "description": "Currency ticker (e.g., ETH, BTC) to filter networks.", "required": false, "schema": { "type": "string" } }, { "name": "include_currency", "in": "query", "description": "Set to true to get the available assets for every network.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "A list of deposit networks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworksResponse" }, "examples": { "withAssets": { "summary": "Response with assets included", "value": [ { "network_name": "ETHEREUM", "assets": [ { "name": "ETH", "contract_address": null }, { "name": "USDC", "contract_address": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238" } ] } ] }, "withoutAssets": { "summary": "Response without assets", "value": [ { "network_name": "ETHEREUM" } ] } } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } } } } }, "/api/v1/withdrawalNetworks/": { "get": { "summary": "Get Withdrawal Networks", "description": "Gets the available withdrawal networks with their assets (currencies). Allows filtering by currency and optionally including currency details.", "operationId": "getWithdrawalNetworks", "tags": [ "Networks" ], "parameters": [ { "name": "currency", "in": "query", "description": "Currency ticker (e.g., ETH, BTC) to filter networks.", "required": false, "schema": { "type": "string" } }, { "name": "include_currency", "in": "query", "description": "Set to true to get the available assets for every network.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "A list of withdrawal networks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworksResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } } } } }, "/api/v1/rates/": { "get": { "summary": "Get Market Rates", "description": "Returns the last market rates (BUY and SELL) for each account pair enabled. These rates are for reference only and do not represent a held rate.", "operationId": "getMarketRates", "tags": [ "Rates" ], "responses": { "200": { "description": "An array of pairs with their associated buy and sell rates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RatesResponse" }, "example": [ { "pair": "ETH_ARS", "last_buy_rate": 1312.1, "last_sell_rate": 1311.1, "final_buy_rate": 1320.1, "final_sell_rate": 1320.1 } ] } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } } } } }, "/api/v1/simulateDeposit/": { "post": { "summary": "Simulate Deposit for On-Ramp (Sandbox)", "description": "Simulates a fiat deposit for an on-ramp transaction in the sandbox environment. Valid for ARS, MXN, and COP currencies with bank_transfer paymentMethodType.", "operationId": "simulateDeposit", "tags": [ "Sandbox" ], "requestBody": { "required": true, "description": "Details for simulating the deposit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateDepositRequest" }, "examples": { "Argentina": { "summary": "Argentina (ARS) - bank_transfer", "value": { "paymentMethodType": "bank_transfer", "amount": 2100, "alias_or_cvu": "1573308578877835214906" } }, "Mexico": { "summary": "Mexico (MXN) - bank_transfer", "value": { "paymentMethodType": "bank_transfer", "amount": 1500, "clabe": "706180196550550550" } }, "Colombia": { "summary": "Colombia (COP) - bank_transfer", "value": { "paymentMethodType": "bank_transfer", "amount": 50000, "payment_url": "https://payment.cobre.co/abc123" } } } } } }, "responses": { "200": { "description": "Deposit simulation successful. Returns 200 OK with empty body.", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "example": {} } } } }, "400": { "description": "Bad Request - e.g., invalid amount, invalid CVU/CLABE/payment URL, or endpoint not applicable for the currency/payment method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } } } } }, "/api/v1/sellAndPays/": { "post": { "summary": "Create Sell and Pay transaction", "description": "Creates a new Sell and Pay transaction for converting cryptocurrency to fiat currency and paying a merchant via QR code. This endpoint automatically cancels any existing Sell and Pay transactions for the same customer. If all required fields are provided (customerId, externalRef, qrCode, paymentCurrency, depositCurrency, depositNetwork, and refundAddress), the transaction will be created with status PENDING. If any required fields are missing, the transaction will be created with status INCOMPLETE and must be completed using the update endpoint.", "operationId": "createSellAndPay", "tags": [ "Sell and Pay" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellAndPayRequest" } } } }, "responses": { "201": { "description": "Sell and Pay transaction successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellAndPayResponse" } } } }, "400": { "description": "Bad Request - e.g., invalid request data, validation error, or the amount is outside the account's SELL limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "AmountBelowMinSellLimit": { "summary": "Amount below the minimum SELL limit", "value": { "code": 20052, "type": "SellAndPayAmountBelowMinSellLimitException", "detail": { "message": "The amount is below the minimum SELL limit." }, "status": 400 } }, "AmountAboveMaxSellLimit": { "summary": "Amount above the maximum SELL limit", "value": { "code": 20053, "type": "SellAndPayAmountAboveMaxSellLimitException", "detail": { "message": "The amount is above the maximum SELL limit." }, "status": 400 } } } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "403": { "description": "Forbidden - QR payments are not enabled for this account. Every Sell and Pay endpoint requires QR payments to be enabled; contact Ripio to enable it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40003, "type": "QrPaymentsNotEnabledException", "detail": { "message": "QR payments are not enabled for this account." }, "status": 403 } } } }, "404": { "description": "Not Found - e.g., Customer not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40004, "type": "NotFound", "detail": { "message": "Not found.", "code": "not_found" }, "status": 404 } } } } } }, "get": { "summary": "List Sell and Pay transactions", "description": "Retrieves a paginated list of Sell and Pay transactions.", "operationId": "listSellAndPay", "tags": [ "Sell and Pay" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "A paginated list of Sell and Pay transactions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedSellAndPayList" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "403": { "description": "Forbidden - QR payments are not enabled for this account. Every Sell and Pay endpoint requires QR payments to be enabled; contact Ripio to enable it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40003, "type": "QrPaymentsNotEnabledException", "detail": { "message": "QR payments are not enabled for this account." }, "status": 403 } } } } } } }, "/api/v1/sellAndPays/{sell_and_pay_id}/": { "get": { "summary": "Retrieve Sell and Pay transaction", "description": "Retrieves detailed information about a specific Sell and Pay transaction by its ID.", "operationId": "retrieveSellAndPay", "tags": [ "Sell and Pay" ], "parameters": [ { "name": "sell_and_pay_id", "in": "path", "description": "The unique identifier of the Sell and Pay transaction", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sell and Pay transaction details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellAndPayResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "404": { "description": "Not Found - Sell and Pay transaction with the specified ID was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40016, "type": "SellAndPayNotFoundException", "detail": { "message": "Sell and Pay not found." }, "status": 404 } } } }, "403": { "description": "Forbidden - QR payments are not enabled for this account. Every Sell and Pay endpoint requires QR payments to be enabled; contact Ripio to enable it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40003, "type": "QrPaymentsNotEnabledException", "detail": { "message": "QR payments are not enabled for this account." }, "status": 403 } } } } } }, "put": { "summary": "Update Sell and Pay transaction", "description": "Updates an existing Sell and Pay transaction to complete or modify its details. Use this endpoint to add missing required fields (depositCurrency, depositNetwork, refundAddress) or update the payment amount. When all required fields are provided, the transaction status will automatically change from INCOMPLETE to PENDING, making it ready for execution.", "operationId": "updateSellAndPay", "tags": [ "Sell and Pay" ], "parameters": [ { "name": "sell_and_pay_id", "in": "path", "required": true, "description": "Unique identifier of the Sell and Pay transaction to update", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellAndPayUpdateRequest" } } } }, "responses": { "200": { "description": "Sell and Pay transaction successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellAndPayResponse" } } } }, "400": { "description": "Bad Request - e.g., invalid request data, validation error, or the amount is outside the account's SELL limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "AmountBelowMinSellLimit": { "summary": "Amount below the minimum SELL limit", "value": { "code": 20052, "type": "SellAndPayAmountBelowMinSellLimitException", "detail": { "message": "The amount is below the minimum SELL limit." }, "status": 400 } }, "AmountAboveMaxSellLimit": { "summary": "Amount above the maximum SELL limit", "value": { "code": 20053, "type": "SellAndPayAmountAboveMaxSellLimitException", "detail": { "message": "The amount is above the maximum SELL limit." }, "status": 400 } } } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "404": { "description": "Not Found - e.g., Sell and Pay transaction not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40016, "type": "SellAndPayNotFoundException", "detail": { "message": "Sell and Pay not found." }, "status": 404 } } } }, "403": { "description": "Forbidden - QR payments are not enabled for this account. Every Sell and Pay endpoint requires QR payments to be enabled; contact Ripio to enable it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40003, "type": "QrPaymentsNotEnabledException", "detail": { "message": "QR payments are not enabled for this account." }, "status": 403 } } } } } }, "delete": { "summary": "Delete Sell and Pay transaction", "description": "Cancels and deletes a Sell and Pay transaction. This operation can be performed on transactions in INCOMPLETE, PENDING, or WAITING_DEPOSIT status. Transactions in RECEIVED_DEPOSIT, CONFIRMED_DEPOSIT, TRADE_COMPLETED, QR_EXECUTION_PENDING, COMPLETED, CANCELED, REFUND_PENDING, or REFUNDED status cannot be deleted as they are already being processed, have been completed, or are in a final state.", "operationId": "deleteSellAndPay", "tags": [ "Sell and Pay" ], "parameters": [ { "name": "sell_and_pay_id", "in": "path", "required": true, "description": "Unique identifier of the Sell and Pay transaction to delete", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Sell and Pay transaction successfully deleted" }, "400": { "description": "Bad Request - e.g., transaction cannot be deleted in its current status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "404": { "description": "Not Found - e.g., Sell and Pay transaction not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40016, "type": "SellAndPayNotFoundException", "detail": { "message": "Sell and Pay not found." }, "status": 404 } } } }, "403": { "description": "Forbidden - QR payments are not enabled for this account. Every Sell and Pay endpoint requires QR payments to be enabled; contact Ripio to enable it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40003, "type": "QrPaymentsNotEnabledException", "detail": { "message": "QR payments are not enabled for this account." }, "status": 403 } } } } } } }, "/api/v1/sellAndPays/{sell_and_pay_id}/execute/": { "post": { "summary": "Execute Sell and Pay transaction", "description": "Executes a Sell and Pay transaction that is in PENDING status. Upon successful execution, the transaction status changes to WAITING_DEPOSIT, indicating that the system is ready to receive the cryptocurrency deposit. The transaction must have all required fields completed before it can be executed. Once in WAITING_DEPOSIT status, the customer can send cryptocurrency to the provided deposit address to complete the payment.", "operationId": "executeSellAndPay", "tags": [ "Sell and Pay" ], "parameters": [ { "name": "sell_and_pay_id", "in": "path", "required": true, "description": "Unique identifier of the Sell and Pay transaction to execute", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sell and Pay transaction successfully executed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellAndPayResponse" } } } }, "400": { "description": "Bad Request - e.g., transaction cannot be executed in its current state (must be in PENDING status), the amount is outside the account's SELL limits, or the customer has no enabled fiat account for the requested currency (Argentina only — Colombia does not require a customer fiat account).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "AmountBelowMinSellLimit": { "summary": "Amount below the minimum SELL limit", "value": { "code": 20052, "type": "SellAndPayAmountBelowMinSellLimitException", "detail": { "message": "The amount is below the minimum SELL limit." }, "status": 400 } }, "AmountAboveMaxSellLimit": { "summary": "Amount above the maximum SELL limit", "value": { "code": 20053, "type": "SellAndPayAmountAboveMaxSellLimitException", "detail": { "message": "The amount is above the maximum SELL limit." }, "status": 400 } }, "NoEnabledFiatAccountForCurrency": { "summary": "Customer has no enabled fiat account for the currency (Argentina only)", "value": { "code": 20051, "type": "NoEnabledFiatAccountForCurrencyException", "detail": { "message": "The customer has no enabled fiat account for the requested currency." }, "status": 400 } } } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "404": { "description": "Not Found - e.g., Sell and Pay transaction not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40016, "type": "SellAndPayNotFoundException", "detail": { "message": "Sell and Pay not found." }, "status": 404 } } } }, "403": { "description": "Forbidden - QR payments are not enabled for this account. Every Sell and Pay endpoint requires QR payments to be enabled; contact Ripio to enable it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40003, "type": "QrPaymentsNotEnabledException", "detail": { "message": "QR payments are not enabled for this account." }, "status": 403 } } } } } } }, "/api/v1/sellAndPays/validateQrCode/": { "post": { "summary": "Validate QR Code", "description": "Validates a QR code and extracts merchant information from it. This endpoint can be used to verify QR codes before creating a Sell and Pay transaction.", "operationId": "validateQrCode", "tags": [ "Sell and Pay" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateQrCodeRequest" } } } }, "responses": { "200": { "description": "QR code validated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateQrCodeResponse" } } } }, "400": { "description": "Bad Request - e.g., invalid QR code format or validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 20048, "type": "InvalidQRCodeException", "detail": { "message": "The QR code is invalid." }, "status": 400 } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "403": { "description": "Forbidden - QR payments are not enabled for this account. Every Sell and Pay endpoint requires QR payments to be enabled; contact Ripio to enable it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40003, "type": "QrPaymentsNotEnabledException", "detail": { "message": "QR payments are not enabled for this account." }, "status": 403 } } } } } } }, "/api/v1/sellAndPays/fiatAccounts/": { "post": { "summary": "Create fiat account for sell and pay", "description": "This step is crucial for optimal performance. Creating the fiat account in advance prevents delays during the first Sell and Pay transaction. Creates a fiat account linked to the customer for Sell and Pay operations. Use this endpoint to pre-create the account and avoid latency during the first Sell and Pay request.\n\nCall this endpoint after KYC completion and before starting any Sell and Pay transaction. If not created beforehand, the account will be automatically created during the first operation, adding extra delay.\n\n**Country support**: Only applicable to Argentina (ARS). For Colombia (COP), Sell and Pay does not require a customer fiat account.", "operationId": "createSellAndPayFiatAccount", "tags": [ "Sell and Pay" ], "security": [ { "BearerToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "customerId" ], "properties": { "customerId": { "type": "string", "format": "uuid", "description": "The unique identifier of the customer for whom to create the fiat account.", "example": "964c8c8c-573d-4f8f-bd2e-8645c3124e74" } } } } } }, "responses": { "201": { "description": "Fiat account successfully created. Returns an empty response body.", "content": { "application/json": { "schema": { "type": "object", "description": "Empty response body on successful creation" } } } }, "400": { "description": "Bad Request. Possible causes:\n- KYC is not approved for the customer.\n- The customer's account country does not require a fiat account for Sell and Pay (e.g. Colombia).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "KycNotApproved": { "summary": "KYC not approved", "value": { "code": 20007, "type": "KycNotApprovedException", "detail": { "message": "KYC for customer '50277a14-2376-4e42-985e-4bc1f7303dc3 - eduardo.perez@ripio.com' is not approved." }, "status": 400 } }, "FiatAccountNotRequired": { "summary": "Fiat account not required for the country (e.g., Colombia)", "value": { "code": 20049, "type": "SellAndPayFiatAccountNotRequiredException", "detail": { "message": "Sell and Pay for country 'CO' does not require a fiat account." }, "status": 400 } }, "InvalidPaymentMethod": { "summary": "Payment method not enabled for the Account", "value": { "code": 20050, "type": "InvalidFiatAccountPaymentMethodException", "detail": { "message": "The payment method 'bank_transfer' does not exist or is disabled for this Account." }, "status": 400 } } } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "404": { "description": "Not Found - Customer not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40004, "type": "NotFound", "detail": { "message": "Customer not found.", "code": "not_found" }, "status": 404 } } } }, "403": { "description": "Forbidden - QR payments are not enabled for this account. Every Sell and Pay endpoint requires QR payments to be enabled; contact Ripio to enable it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40003, "type": "QrPaymentsNotEnabledException", "detail": { "message": "QR payments are not enabled for this account." }, "status": 403 } } } } } } }, "/api/v1/customers/{customerId}/termsAcceptance/": { "get": { "summary": "Get Terms Acceptance Status", "description": "Returns whether the customer has accepted the currently active Terms and Conditions for their account's country, along with the active T&C details.\n\nUse this endpoint to check whether to show the T&C acceptance screen to the customer before proceeding with on-ramp or off-ramp operations.\n\nWhen no active Terms and Conditions exist for the country, `accepted` is always `true` and the term fields (`termsId`, `version`, `url`) are `null` \u2014 the customer is not blocked.", "operationId": "getTermsAcceptanceStatus", "tags": [ "Terms and Conditions" ], "parameters": [ { "$ref": "#/components/parameters/CustomerId" } ], "responses": { "200": { "description": "Terms acceptance status retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsAcceptanceStatusResponse" }, "examples": { "Accepted": { "summary": "Customer has accepted the active T&C", "value": { "termsId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "country": "AR", "version": "1.0", "url": "https://example.com/terms/v1.0", "accepted": true, "acceptedAt": "2024-06-01T12:00:00Z" } }, "NotAccepted": { "summary": "Customer has not yet accepted the active T&C", "value": { "termsId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "country": "AR", "version": "1.0", "url": "https://example.com/terms/v1.0", "accepted": false, "acceptedAt": null } }, "NoActiveTerms": { "summary": "No active T&C for the country \u2014 customer is not blocked", "value": { "termsId": null, "country": "AR", "version": null, "url": null, "accepted": true, "acceptedAt": null } } } } } }, "401": { "description": "Unauthorized - Invalid or missing access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 40001, "type": "NotAuthenticated", "detail": { "message": "Authentication credentials were not provided.", "code": "not_authenticated" }, "status": 401 } } } }, "404": { "description": "Not Found - Customer does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": 20001, "type": "CustomerNotFoundException", "detail": { "message": "Customer not found." }, "status": 404 } } } } } } } }, "tags": [ { "name": "Authentication", "description": "Operations related to API authentication and authorization." }, { "name": "Support Tickets", "description": "Operations for raising and tracking customer support tickets with Ripio's support team. This feature must be enabled for your account by the Ripio team." }, { "name": "Customers", "description": "Operations related to customer management." }, { "name": "KYC", "description": "Operations related to Know Your Customer processes." }, { "name": "Fiat Accounts", "description": "Operations related to managing fiat accounts and their requirements." }, { "name": "Quotes", "description": "Operations related to obtaining and managing conversion quotes." }, { "name": "On-Ramp", "description": "Operations related to fiat-to-crypto (on-ramp) processes." }, { "name": "Off-Ramp", "description": "Operations related to crypto-to-fiat (off-ramp) processes." }, { "name": "Transactions", "description": "Operations related to listing and managing all transaction types." }, { "name": "Networks", "description": "Operations related to retrieving available deposit and withdrawal networks." }, { "name": "Rates", "description": "Operations related to retrieving market rates." }, { "name": "Transaction Limits", "description": "Operations related to retrieving per-transaction limits by currency and ramp operation." }, { "name": "Sandbox", "description": "Operations specific to the sandbox environment for testing purposes." }, { "name": "Webhooks", "description": "Webhook event notifications from Ripio Ramp API." }, { "name": "Sell and Pay", "description": "Endpoints for managing Sell and Pay transactions, which allow customers to convert cryptocurrency to fiat currency and pay merchants via QR codes" } ] }