> ## Documentation Index > Fetch the complete documentation index at: https://docs.zeam.money/llms.txt > Use this file to discover all available pages before exploring further. # Collect an on-ramp payment > Collects from a registered counterparty's mobile-money payment destination and pays the proceeds into one of your own wallets, executed asynchronously against a quote from POST /v1/quotes?type=onramp. The roles are the reverse of an off-ramp: `senderId` is the counterparty who pays (a beneficiary record in your association), `paymentDestinationId` is the payment destination the collection debits, and `walletId` is your wallet the payout lands in. Pricing is never accepted from the caller; it is resolved server-side from the quote. The wallet must be verified (403 otherwise). The counterparty's classification must match the corridor the quote was priced for, and the fields the connector requires must be present on the counterparty and payment destination; a submission that falls short returns a 422 with field-level detail. `notifyEmail` and `notifyWhatsApp` notify your own business, at the email or mobile number on your registered profile. Returns 202. ## OpenAPI ````yaml /api-reference/openapi.yaml post /payments/onramp openapi: 3.1.0 info: title: Zeam API Gateway version: 1.0.0 description: > The Zeam API Gateway is the single, REST-based external surface for registered integrators. Every request, including token issuance, carries the application secret header `x-zeam-auth` — there is no unauthenticated route. Protected requests additionally carry a bearer access token obtained from POST /v1/auth/token; the gateway verifies it and resolves the caller's association server-side — you do not need to supply an association id header. Errors use RFC 7807 `application/problem+json`. license: name: Proprietary url: https://zeam.app contact: name: Zeam Platform Team url: https://zeam.app servers: - url: https://api.zeam.money/gw/v1 description: >- Zeam API Gateway. The sandbox and production environments share this base URL; your application's registration determines which one a request runs in. security: - BearerAuth: [] ZeamAuth: [] tags: - name: Auth description: Public token issuance. - name: Wallets description: Association wallets with embedded balances. - name: Assets description: Platform asset registry. - name: Beneficiaries description: Association beneficiaries and their payment destinations. - name: Connectors description: Connector discovery. - name: Quotes description: Off-ramp and on-ramp quotes. - name: Payments description: >- P2P transfers, swaps, off-ramp cash-outs, and on-ramp collections, plus the compliance reference lookups used when building an off-ramp or on-ramp. - name: Transactions description: Transaction records, the polling and history complement to webhooks. - name: Webhooks description: Association webhook registrations. paths: /payments/onramp: post: tags: - Payments summary: Collect an on-ramp payment description: | Collects from a registered counterparty's mobile-money payment destination and pays the proceeds into one of your own wallets, executed asynchronously against a quote from POST /v1/quotes?type=onramp. The roles are the reverse of an off-ramp: `senderId` is the counterparty who pays (a beneficiary record in your association), `paymentDestinationId` is the payment destination the collection debits, and `walletId` is your wallet the payout lands in. Pricing is never accepted from the caller; it is resolved server-side from the quote. The wallet must be verified (403 otherwise). The counterparty's classification must match the corridor the quote was priced for, and the fields the connector requires must be present on the counterparty and payment destination; a submission that falls short returns a 422 with field-level detail. `notifyEmail` and `notifyWhatsApp` notify your own business, at the email or mobile number on your registered profile. Returns 202. operationId: createOnrampPayment requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OnrampPaymentRequest' example: transactionId: 5f0c6e2a-3436-11e5-bf7f-0002a5d5c51b walletId: 66666666-6666-6666-6666-666666666666 senderId: 77777777-7777-7777-7777-777777777777 paymentDestinationId: aaaa1111-2222-3333-4444-555566667777 quoteId: cccc1111-2222-3333-4444-555566667777 purpose: FAMILY_SUPPORT responses: '202': description: On-ramp accepted for asynchronous processing. content: application/json: schema: $ref: '#/components/schemas/PaymentAccepted' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationError' '502': $ref: '#/components/responses/UpstreamError' '504': $ref: '#/components/responses/UpstreamTimeout' components: schemas: OnrampPaymentRequest: type: object required: - transactionId - walletId - senderId - paymentDestinationId - quoteId properties: transactionId: type: string format: uuid description: Your transaction id. Replaying it returns the original result. walletId: type: string format: uuid description: Your own wallet the payout lands in. senderId: type: string format: uuid description: >- The paying counterparty, a beneficiary registered in your association. paymentDestinationId: type: string format: uuid description: The counterparty's payment destination the collection debits. quoteId: type: string format: uuid description: A quote from POST /v1/quotes?type=onramp. purpose: type: string description: Purpose of remittance. Discover values via GET /v1/payments/enums. fromRef: type: - string - 'null' maxLength: 16 pattern: ^[A-Za-z0-9-]{1,16}$ description: >- Optional sender-side transaction reference. When supplied: 1-16 characters, letters, digits, and hyphens only. Omit it or send null for no reference. toRef: type: - string - 'null' maxLength: 16 pattern: ^[A-Za-z0-9-]{1,16}$ description: >- Optional recipient-side transaction reference. When supplied: 1-16 characters, letters, digits, and hyphens only. Omit it or send null for no reference. senderSourceOfFunds: type: string description: The counterparty's source of funds, when the connector requires it. senderIdCountryIsoCode: type: string description: >- ISO 3166-1 alpha-2 country that issued the counterparty's ID, when the connector requires it. receiverSourceOfFunds: type: string description: Your source of funds, when the connector requires it. notifyEmail: type: boolean description: >- Notify your business by email at the address on your registered profile. Mutually exclusive with notifyWhatsApp. notifyWhatsApp: type: boolean description: >- Notify your business by WhatsApp at the mobile number on your registered profile. Mutually exclusive with notifyEmail. PaymentAccepted: type: object required: - transactionRecordId - status description: >- A 202 means the submission was accepted for asynchronous execution, not that it settled. Track completion with the Transactions routes or webhooks. properties: transactionRecordId: type: string format: uuid description: >- The transaction record id, used with GET /v1/transactions/{transactionId}. intentId: type: string description: Execution intent id, when present. status: type: string description: Submission status; not a terminal transaction status. example: accepted isIdempotent: type: boolean description: >- True when this response replays a prior submission with the same transactionId. message: type: string Problem: type: object required: - type - title - status description: RFC 7807 problem details. properties: type: type: string format: uri example: https://errors.zeam.app/validation-error title: type: string example: Validation Error status: type: integer example: 422 detail: type: string example: The 'amount' field must be a positive decimal. instance: type: string example: /v1/quotes requestId: type: string example: 01J8Z6K3QW9F2 errors: type: array items: type: object properties: field: type: string message: type: string responses: BadRequest: description: Malformed request. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Unauthorized: description: Missing or invalid authentication. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Forbidden: description: Authenticated but not permitted. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' NotFound: description: Resource not found. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' ValidationError: description: Request failed validation. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' UpstreamError: description: An unexpected error occurred while completing the request. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' UpstreamTimeout: description: The request timed out. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: Access token issued by POST /v1/auth/token. ZeamAuth: type: apiKey in: header name: x-zeam-auth description: >- Application secret (the apiKey issued at registration), required on every request. ````