Bitpagos Customers API

openapi: 3.2.0
info:
  title: Bitpagos Customers API
  version: '2026-09-28'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-09-28: 16 operation(s) read from 14 public documentation page(s) (each operation names its page in x-source). This is not the provider''s published contract; Bitpagos has published no machine-readable contract that the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 5
    documentation: 11
    pages-with-code: 4
    pages-read: 14
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-09-28'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://apidocs.ripio.com/static/api/overview
  - https://docs.ripio.com/ramps-api/kyc/start-kyc.md
  - https://docs.ripio.com/ramps-api/kyc/reusable-kyc.md
  - https://docs.ripio.com/ramps-api/refunds/overview.md
  - https://docs.ripio.com/ramps-api/kyc/kyc-with-ripio.md
  - https://docs.ripio.com/ramps-api/kyc/resend-kyc-otp.md
  - https://docs.ripio.com/ramps-api/quotes/create-quote.md
  - https://docs.ripio.com/ramps-api/kyc/validate-kyc-otp.md
  - https://docs.ripio.com/ramps-api/rates/get-market-rates.md
  - https://docs.ripio.com/ramps-api/refunds/refund-deposit.md
  - https://docs.ripio.com/ramps-api/sandbox/kyc-in-sandbox.md
  - https://docs.ripio.com/ramps-api/fiat-accounts/list-banks.md
  - https://docs.ripio.com/ramps-api/customers/create-customer.md
  - https://docs.ripio.com/ramps-api/customers/update-customer.md
servers:
- url: https://skala-sandbox.ripio.com
security:
- bearer: []
tags:
- name: Customers
paths:
  /api/v1/customers/:
    post:
      operationId: post_api_v1_customers
      tags:
      - Customers
      summary: Create Customer
      x-source: https://docs.ripio.com/ramps-api/customers/create-customer.md
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1CustomersRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1CustomersResponse'
      x-evidence:
        kind: documentation
  /api/v1/customers/{customerid}:
    put:
      operationId: put_api_v1_customers_customerid
      tags:
      - Customers
      summary: Update Customer
      description: Updates an existing customer's information. Currently, only the email address can be updated. Once the customer's KYC has been approved, this endpoint can no longer change the email — see the `email` field description and the `400` response below.
      x-source: https://docs.ripio.com/ramps-api/customers/update-customer.md
      parameters:
      - name: customerid
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutApiV1CustomersCustomeridRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PutApiV1CustomersCustomeridResponse'
      x-evidence:
        kind: documentation
  /api/v1/customers/{customerid}/kyc/otp/resend/:
    post:
      operationId: post_api_v1_customers_customerid_kyc_otp_resend
      tags:
      - Customers
      summary: Resend KYC OTP
      description: Resends the email OTP for a KYC verification that is waiting on it. Only works while the verification is pending OTP confirmation — call Start KYC first.
      x-source: https://docs.ripio.com/ramps-api/kyc/resend-kyc-otp.md
      parameters:
      - name: customerid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/customers/{customerid}/kyc/otp/validate/:
    post:
      operationId: post_api_v1_customers_customerid_kyc_otp_validate
      tags:
      - Customers
      summary: Validate KYC OTP
      x-source: https://docs.ripio.com/ramps-api/kyc/validate-kyc-otp.md
      parameters:
      - name: customerid
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1CustomersCustomeridKycOtpValidateRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1CustomersCustomeridKycOtpValidateResponse'
      x-evidence:
        kind: documentation
  /api/v1/customers/{customerid}/kyc/start:
    post:
      operationId: post_api_v1_customers_customerid_kyc_start
      tags:
      - Customers
      summary: Start KYC
      description: Starts a KYC verification for the customer. Takes no identity data — only a required `redirectUrl` and an optional `kycProviderShareToken`.
      x-source: https://docs.ripio.com/ramps-api/kyc/start-kyc.md
      parameters:
      - name: customerid
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1CustomersCustomeridKycStartRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1CustomersCustomeridKycStartResponse'
      x-evidence:
        kind: documentation
  /api/v1/customers/{customerid}/refundableDeposits/{deposituuid}/refund/:
    post:
      operationId: post_api_v1_customers_customerid_refundableDeposits_deposituuid_refund
      tags:
      - Customers
      summary: Refund a Deposit
      x-source: https://docs.ripio.com/ramps-api/refunds/refund-deposit.md
      parameters:
      - name: customerid
        in: path
        required: true
        schema:
          type: string
      - name: deposituuid
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1CustomersCustomeridRefundabledepositsDeposituuidRef'
      responses:
        '202':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1CustomersCustomeridRefundabledepositsDeposituuidRef2'
      x-evidence:
        kind: documentation
  /customers/{customerid}/kyc:
    post:
      operationId: post_customers_customerid_kyc
      tags:
      - Customers
      summary: Add the root-level `kycProviderShareToken` field to the call that opens the…
      x-source: https://docs.ripio.com/ramps-api/kyc/reusable-kyc.md
      parameters:
      - name: customerid
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCustomersCustomeridKycRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostCustomersCustomeridKycResponse'
      x-evidence:
        kind: documentation
  /customers/{customerid}/refundableCryptoDeposits/{depositid}/refund:
    post:
      operationId: post_customers_customerid_refundableCryptoDeposits_depositid_refund
      tags:
      - Customers
      summary: A crypto deposit with no order
      x-source: https://docs.ripio.com/ramps-api/refunds/overview.md
      parameters:
      - name: customerid
        in: path
        required: true
        schema:
          type: string
      - name: depositid
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /customers/{customerid}/refundableDeposits/{deposituuid}/refund:
    post:
      operationId: post_customers_customerid_refundableDeposits_deposituuid_refund
      tags:
      - Customers
      summary: A fiat deposit with no order
      x-source: https://docs.ripio.com/ramps-api/refunds/overview.md
      parameters:
      - name: customerid
        in: path
        required: true
        schema:
          type: string
      - name: deposituuid
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /customers/{customerid}/transactions/{transactionid}/{orderid}/refund:
    post:
      operationId: post_customers_customerid_transactions_transactionid_orderid_refund
      tags:
      - Customers
      summary: A failed off-ramp order (customer‑scoped form)
      x-source: https://docs.ripio.com/ramps-api/refunds/overview.md
      parameters:
      - name: customerid
        in: path
        required: true
        schema:
          type: string
      - name: transactionid
        in: path
        required: true
        schema:
          type: string
      - name: orderid
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
        collapsed_from: 2 example path(s) differing only at transactionId
components:
  schemas:
    PostCustomersCustomeridKycRequest:
      type: object
      properties:
        redirectUrl:
          type: string
        kycProviderShareToken:
          type: string
      required:
      - redirectUrl
      - kycProviderShareToken
    PutApiV1CustomersCustomeridResponse:
      type: object
      properties:
        '200':
          type: string
          description: Customer updated successfully.
        '400':
          type: string
          description: Bad Request - The email cannot be changed because the customer's KYC is already approved. Contact Ripio support to change it in that case.
        '401':
          type: string
          description: Unauthorized - Invalid or missing access token.
        '404':
          type: string
          description: Not Found - Customer not found or inactive.
    PostApiV1CustomersCustomeridKycStartResponse:
      type: object
      properties:
        submissionId:
          type: string
          description: Unique identifier for the submitted KYC data.
        createdAt:
          type: string
          description: Date and time the KYC submission was created (UTC format).
        providerUrl:
          type: string
          description: Points to a third‑party KYC provider's widget to handle file uploads and liveness checks.
        otpRequired:
          type: boolean
          description: Whether the OTP sent to the customer's email still needs to be validated.
    PostApiV1CustomersCustomeridKycOtpValidateRequest:
      type: object
      properties:
        code:
          type: string
          description: The OTP code to verify.
      required:
      - code
    PostCustomersCustomeridKycResponse:
      type: object
      properties:
        submissionId:
          type: string
        providerUrl:
          type: string
        createdAt:
          type: string
          description: ISO‑8601 timestamp
    PostApiV1CustomersRequest:
      type: object
      properties:
        customerId:
          type: string
          description: Optional customer identifier supplied by the partner. If you send it, it **must be a valid UUID** — any other value is rejected with a 400. If you omit it, Ripio generates one and returns it in the response.
        email:
          type: string
          description: The email of the individual or juridical person.
        phoneNumber:
          type: string
          description: Optional phone number for the customer.
        type:
          type: string
          description: The type of customer involved.
      required:
      - email
      - type
    PostApiV1CustomersResponse:
      type: object
      properties:
        customerId:
          type: string
          description: A unique customer's ID. Either the one you supplied on creation or the one Ripio generated for you.
        email:
          type: string
          description: The email of the individual or juridical person.
        phoneNumber:
          type: string
          description: The phone number of the individual or juridical person. `null` if not provided.
        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.
        createdAt:
          type: string
          description: The date and time of customer's creation.
    PutApiV1CustomersCustomeridRequest:
      type: object
      properties:
        email:
          type: string
          description: The new email for the customer. Accepted while the customer's KYC has not been approved yet — no email set, no KYC submitted, one currently in progress, or a previous attempt that failed. Once the KYC is approved, this field is rejected with `400` and error code `20081` (`CustomerEmailFrozenException`); contact Ripio support to change it in that case.
      required:
      - email
    PostApiV1CustomersCustomeridKycStartRequest:
      type: object
      properties:
        redirectUrl:
          type: string
          description: URL to redirect the user to after completing the KYC flow.
        kycProviderShareToken:
          type: string
          description: Optional. Sumsub share token for a customer already verified in your own Sumsub account (Reusable KYC).
      required:
      - redirectUrl
    PostApiV1CustomersCustomeridRefundabledepositsDeposituuidRef:
      type: object
      properties:
        fiatAccountId:
          type: string
          description: Identifier of an ENABLED fiat account of the same customer, where the money is returned. Rejected by providers that refund to the account the customer paid from.
    PostApiV1CustomersCustomeridRefundabledepositsDeposituuidRef2:
      type: object
      properties:
        refundId:
          type: string
          description: Unique identifier of the refund.
        status:
          type: string
          description: Current state of the refund.
        depositUuid:
          type: string
          description: Identifier of the deposit being refunded.
        initiatedBy:
          type: string
          description: Who originated the refund this response is about.
    PostApiV1CustomersCustomeridKycOtpValidateResponse:
      type: object
      properties:
        submissionId:
          type: string
          description: Unique identifier for the submitted KYC data.
        createdAt:
          type: string
          description: Date and time the KYC submission was created (UTC format).
        providerUrl:
          type: string
          description: Points to a third‑party KYC provider's widget to handle file uploads and liveness checks. Only available in production.
        otpRequired:
          type: boolean
          description: Whether the OTP sent to the customer's email still needs to be validated before continuing.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer