> ## Documentation Index > Fetch the complete documentation index at: https://docs.services.payward.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Ramp checkout session > Creates a Ramp checkout for a selected user and returns the widget redirect URL with the checkout UUID in the fragment. No access token is minted here; the widget mints it via the bootstrap call (`BootstrapRampCheckout`). The URL must still be treated as sensitive because the UUID is a capability handle. For loginless SEPA checkouts, submit `from.method = "sepa"`, `from.symbol = "EUR"`, and an EEA `country`. ## OpenAPI ````yaml https://d2588n1sy4m36o.cloudfront.net/uat/merged/openapi.json post /v1/users/{user_id}/ramp/checkouts openapi: 3.1.0 info: title: PWS Public API version: '1' description: >- Integrate with Payward Services to onboard users, manage accounts and funds, trade assets, and receive event notifications. contact: name: Payward Services servers: - url: https://api.sandbox.services.payward.com security: [] tags: - name: Assets description: List the assets PWS is willing to swap. x-displayName: Assets - name: Conversions description: >- Rule-driven and on-demand fiat ↔ crypto value movement, including conversion rules and deposits. x-displayName: Conversions - name: Auto Earn description: >- Manage Auto Earn preferences and retrieve allocation and reward information. x-displayName: Auto Earn - name: Bonded Earn description: >- Allocate funds to and deallocate funds from bonded earn strategies, review allocations, and track request status. x-displayName: Bonded Earn - name: Funding description: >- Discover deposit and withdrawal options, manage deposit addresses, and move funds between accounts. x-displayName: Funding - name: Derivative transfers description: >- Move funds between an account's spot balance and the same owner's futures balance. x-displayName: Derivative transfers - name: Portfolio description: 'Inspect a customer''s portfolio: balances, valuations, and transactions.' x-displayName: Portfolio - name: Ramp description: >- Support Ramp flows with discovery, quotes, limits, and hosted checkout experiences. x-displayName: Ramp - name: Reports description: Settlement and reconciliation reports for the partner. x-displayName: Reports - name: Swaps description: Account-funded quotes that lock a price until they expire or are executed. x-displayName: Swaps - name: Onchain quotes description: Wallet-funded quotes that return the data needed to settle onchain. x-displayName: Onchain quotes - name: Price trigger swaps description: Swaps that wait for a target price before submitting a trade. x-displayName: Price trigger swaps - name: Travel Rule verifications description: Travel Rule address ownership verification flows. x-displayName: Travel Rule verifications - name: Users description: >- User onboarding and status flows that the partner manages. - **Create User** provisions an account-owned user from an external reference and optional email. - **Get User** retrieves the user's profile, verification status, and required actions. Use the returned user `id` for calls that require the user's identifier. x-displayName: Users - name: Verifications description: Identity verification (KYC) submission and status for end users. x-displayName: Verifications - name: Webhooks description: >- Register HTTPS destinations to receive event deliveries, rotate signing secrets, and inspect, update, or delete existing subscriptions. Each subscription is owned by the authenticated partner; deliveries are signed with HMAC-SHA256 and retried on transient failures. x-displayName: Webhooks paths: /v1/users/{user_id}/ramp/checkouts: post: tags: - Ramp summary: Create Ramp checkout session description: >- Creates a Ramp checkout for a selected user and returns the widget redirect URL with the checkout UUID in the fragment. No access token is minted here; the widget mints it via the bootstrap call (`BootstrapRampCheckout`). The URL must still be treated as sensitive because the UUID is a capability handle. For loginless SEPA checkouts, submit `from.method = "sepa"`, `from.symbol = "EUR"`, and an EEA `country`. operationId: createRampCheckoutSession parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: content: application/json: schema: description: >- Request to create a token-bound Ramp checkout session. The `from`/`to` pairing determines the Ramp direction. Only on-ramp (`from` fiat, `to` crypto or stablecoin) is currently supported; other pairings are rejected with `400 BadRequest`. For loginless SEPA checkouts, submit `from.method = "sepa"`, `from.symbol = "EUR"`, and an EEA `country`. type: object properties: from: description: Asset the user pays with at checkout. type: object properties: symbol: $ref: '#/components/schemas/AssetSymbol' description: >- Asset ticker symbol (e.g., "USD"). Required. Use `GET /v1/ramp/fiat-currencies` to discover supported source currencies. type: $ref: '#/components/schemas/Ramp_SourceAssetType' method: description: >- Funding method used for the source side. Required. Use `GET /v1/ramp/payment-methods` to discover supported payment methods. type: string minLength: 1 maxLength: 128 amount: description: >- Amount to spend, denominated in the source asset, as a decimal string. Required. type: string pattern: ^[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 title: RampCheckoutFrom required: - symbol - method - amount to: description: Asset the user receives at checkout. type: object properties: symbol: $ref: '#/components/schemas/AssetSymbol' description: >- Asset ticker symbol (e.g., "BTC"). Required. Use `GET /v1/ramp/buy/crypto` to discover supported destination assets. type: $ref: '#/components/schemas/Ramp_DestinationAssetType' method: description: >- Withdrawal method for the destination asset. Required. Use `GET /v1/ramp/buy/crypto` to discover available withdrawal methods for each asset. type: string minLength: 1 maxLength: 128 network: description: >- Optional withdrawal network identifier. Use `GET /v1/ramp/buy/crypto` to discover available networks for each destination asset. type: string minLength: 1 maxLength: 128 address: description: >- Optional destination wallet address for the crypto withdrawal. type: string minLength: 1 maxLength: 512 memo: description: >- Optional memo/tag/note for the crypto withdrawal (used for certain assets). type: string minLength: 1 maxLength: 256 title: RampCheckoutTo required: - symbol - method affiliate_fee_bps: description: >- Affiliate fee in basis points to attribute to the partner (0-10000 where 100 = 1%). type: string pattern: ^(10000|[0-9]{1,4})$ minLength: 1 maxLength: 5 country: description: >- ISO 3166-1 alpha-2 country code. Use `GET /v1/ramp/countries` to discover supported values. type: string pattern: ^[A-Za-z]{2}$ minLength: 2 maxLength: 2 subdivision: description: >- ISO 3166-2 subdivision code suffix (e.g., `CA` for California when country is `US`). Use `GET /v1/ramp/countries` to discover supported values. type: string pattern: ^[A-Za-z0-9-]+$ minLength: 1 maxLength: 64 redirect_url: description: >- URL to redirect the user after completing checkout successfully. type: string minLength: 1 maxLength: 255 failure_url: description: URL to redirect the user after a failed checkout. type: string minLength: 1 maxLength: 255 external_user_id: description: Optional partner-supplied user identifier. type: string minLength: 1 maxLength: 64 external_partner_id: description: Optional partner-supplied partner identifier. type: string minLength: 1 maxLength: 64 external_transaction_id: description: Optional partner transaction identifier. type: string minLength: 1 maxLength: 64 external_metadata: description: Optional metadata to store alongside the checkout. type: string minLength: 1 maxLength: 1000 required: - from - to - country examples: create-checkout: summary: Create hosted checkout value: from: symbol: USD type: fiat method: credit_card amount: '100.00' to: symbol: BTC type: crypto method: Bitcoin network: Bitcoin address: bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh memo: '123456' affiliate_fee_bps: '250' country: US subdivision: CA redirect_url: https://example.com/checkout/success failure_url: https://example.com/checkout/failure external_user_id: user_01J0M7C0Z9F8YX3GQH8E external_partner_id: partner_456 external_transaction_id: INV-2026-04-0042 external_metadata: '{"order_id":"order_12345"}' required: true responses: '200': description: Successful response headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: type: object properties: data: description: Created checkout session details. type: object properties: checkout_id: description: Public checkout session identifier. type: string minLength: 36 maxLength: 36 checkout_url: description: >- Widget redirect URL with the checkout UUID in the fragment. No access token is present; the widget mints one via the bootstrap call. The UUID is a capability handle, so the URL is still sensitive. type: string minLength: 1 maxLength: 2048 expires_in: description: >- Checkout URL validity window, in seconds. This is how long the partner has to redirect the user before the handle should be considered stale. This is the creation-to-bootstrap window, not a token lifetime; the token TTL starts at bootstrap and is reported there. type: integer format: int64 minimum: 0 request_data: description: Original request payload for client confirmation. type: object properties: from: description: Echo of the source (pay) side of the checkout. type: object properties: symbol: $ref: '#/components/schemas/AssetSymbol' description: >- Asset ticker symbol (e.g., "USD"). Required. Use `GET /v1/ramp/fiat-currencies` to discover supported source currencies. type: $ref: '#/components/schemas/Ramp_SourceAssetType' method: description: >- Funding method used for the source side. Required. Use `GET /v1/ramp/payment-methods` to discover supported payment methods. type: string minLength: 1 maxLength: 128 amount: description: >- Amount to spend, denominated in the source asset, as a decimal string. Required. type: string pattern: ^[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 title: RampCheckoutFrom required: - symbol - method - amount to: description: >- Echo of the destination (receive) side of the checkout. type: object properties: symbol: $ref: '#/components/schemas/AssetSymbol' description: >- Asset ticker symbol (e.g., "BTC"). Required. Use `GET /v1/ramp/buy/crypto` to discover supported destination assets. type: $ref: '#/components/schemas/Ramp_DestinationAssetType' method: description: >- Withdrawal method for the destination asset. Required. Use `GET /v1/ramp/buy/crypto` to discover available withdrawal methods for each asset. type: string minLength: 1 maxLength: 128 network: description: >- Optional withdrawal network identifier. Use `GET /v1/ramp/buy/crypto` to discover available networks for each destination asset. type: string minLength: 1 maxLength: 128 address: description: >- Optional destination wallet address for the crypto withdrawal. type: string minLength: 1 maxLength: 512 memo: description: >- Optional memo/tag/note for the crypto withdrawal (used for certain assets). type: string minLength: 1 maxLength: 256 title: RampCheckoutTo required: - symbol - method affiliate_fee_bps: description: >- Affiliate fee in basis points (0-10000 where 100 = 1%). type: string pattern: ^(10000|[0-9]{1,4})$ minLength: 1 maxLength: 5 country: description: ISO 3166-1 alpha-2 country code type: string pattern: ^[A-Za-z]{2}$ minLength: 2 maxLength: 2 subdivision: description: >- ISO 3166-2 subdivision code suffix (e.g., CA for California when country is US) type: string pattern: ^[A-Za-z0-9-]+$ minLength: 1 maxLength: 64 redirect_url: description: >- URL where the ramp provider should redirect the user after successful checkout type: string minLength: 1 maxLength: 255 failure_url: description: >- URL where the ramp provider should redirect the user after failed checkout type: string minLength: 1 maxLength: 255 external_user_id: description: >- Partner-provided user identifier (max 64 characters) type: string minLength: 1 maxLength: 64 external_partner_id: description: >- Partner-provided partner identifier (max 64 characters) type: string minLength: 1 maxLength: 64 external_transaction_id: description: >- Partner-provided transaction identifier (max 64 characters) type: string minLength: 1 maxLength: 64 external_metadata: description: >- Additional partner-provided metadata (max 1000 characters) type: string minLength: 1 maxLength: 1000 title: RampCheckoutRequestData required: - country title: RampCreatedCheckoutData required: - checkout_id - checkout_url - expires_in required: - data examples: checkout-created: summary: Created hosted checkout value: data: checkout_id: 018fdb88-4a87-73b2-9b9f-b5f38d11b924 checkout_url: >- https://ramp.kraken.com/confirmation#checkout_id=018fdb88-4a87-73b2-9b9f-b5f38d11b924 expires_in: 600 request_data: from: symbol: USD type: fiat method: credit_card amount: '100.00' to: symbol: BTC type: crypto method: Bitcoin network: Bitcoin address: bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh memo: '123456' affiliate_fee_bps: '250' country: US subdivision: CA redirect_url: https://example.com/checkout/success failure_url: https://example.com/checkout/failure external_user_id: user_01J0M7C0Z9F8YX3GQH8E external_partner_id: partner_456 external_transaction_id: INV-2026-04-0042 external_metadata: '{"order_id":"order_12345"}' '400': $ref: '#/components/responses/RampBadRequestResponse' '401': $ref: '#/components/responses/RampUnauthenticatedResponse' '403': $ref: '#/components/responses/RampForbiddenResponse' '429': $ref: '#/components/responses/RampResourceExhaustedResponse' '500': $ref: '#/components/responses/RampInternalResponse' '501': $ref: '#/components/responses/RampUnimplementedResponse' '503': $ref: '#/components/responses/RampUnavailableResponse' '504': $ref: '#/components/responses/RampDeadlineExceededResponse' security: - ApiKey: [] ApiSign: [] ApiNonce: [] components: parameters: UserId: name: user_id in: path required: true example: AA23N84GGQN4WE6I schema: $ref: '#/components/schemas/UserId' IdempotencyKey: name: Idempotency-Key in: header required: false schema: $ref: '#/components/schemas/IdempotencyKey' example: 550e8400-e29b-41d4-a716-446655440000 schemas: AssetSymbol: description: Symbol identifying an asset within its asset category. type: string minLength: 1 maxLength: 16 Ramp_SourceAssetType: description: Source asset classification accepted by Ramp on-ramp flows. type: string enum: - fiat default: fiat Ramp_DestinationAssetType: description: Destination asset classification accepted by Ramp on-ramp flows. type: string enum: - crypto - stablecoin default: crypto UserId: description: Globally unique public identifier for a user. type: string minLength: 14 maxLength: 42 IdempotencyKey: description: >- Client-generated canonical UUIDv4 that uniquely identifies a request for safe retries. type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 550e8400-e29b-41d4-a716-446655440000 BadRequestError: title: Bad Request description: Request validation failed or the request could not be processed. oneOf: - title: Bad Request allOf: - $ref: '#/components/schemas/PwsValidationErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsValidationError' - type: object required: - status - code properties: status: type: integer format: int32 const: 400 code: type: string enum: - bad_request - title: Gateway description: >- Gateway-level validation failure returned before the request reaches the service. allOf: - $ref: '#/components/schemas/PwsValidationErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsValidationError' - type: object required: - status - code properties: type: type: string const: service_error status: type: integer format: int32 const: 400 code: type: string const: gateway UnauthenticatedError: title: Unauthenticated description: Authentication credentials are missing, invalid, or not accepted. oneOf: - title: Unauthenticated allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 401 code: type: string enum: - unauthenticated - title: Gateway description: Authentication failure returned by the API gateway. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: type: type: string const: service_error status: type: integer format: int32 const: 401 code: type: string const: gateway ForbiddenError: title: Forbidden description: The caller is not allowed to perform this operation. oneOf: - title: Forbidden allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 403 code: type: string enum: - forbidden - title: Gateway description: Authorization failure returned by the API gateway. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: type: type: string const: service_error status: type: integer format: int32 const: 403 code: type: string const: gateway ResourceExhaustedError: description: The request was rate limited or a resource quota was exhausted. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 429 code: type: string enum: - resource_exhausted InternalError: description: An unexpected server-side error occurred. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 500 code: type: string enum: - internal UnimplementedError: description: The requested operation is not implemented. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 501 code: type: string enum: - unimplemented UnavailableError: description: The service is temporarily unavailable. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 503 code: type: string enum: - unavailable DeadlineExceededError: description: The request deadline was exceeded before a response could be produced. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 504 code: type: string enum: - deadline_exceeded PwsValidationErrorEnvelope: description: Error envelope for request validation failures. type: object required: - error properties: error: $ref: '#/components/schemas/PwsValidationError' description: Validation error details. PwsValidationError: description: Standard PWS API error object for request validation failures. type: object required: - type - status - instance - code properties: type: description: Machine-readable error class. type: string status: description: HTTP status code returned for this error. type: integer format: int32 instance: description: Request identifier for this specific error occurrence. type: string code: description: Stable machine-readable error code. type: string doc_url: description: Optional link to documentation for this error. type: string format: uri causes: description: Validation failures that contributed to the error. type: array items: $ref: '#/components/schemas/PwsErrorCause' PwsGeneralErrorEnvelope: description: Error envelope for operational or domain failures. type: object required: - error properties: error: $ref: '#/components/schemas/PwsGeneralError' description: General error details. PwsGeneralError: description: Standard PWS API error object for non-validation failures. allOf: - $ref: '#/components/schemas/PwsErrorBase' - type: object properties: causes: description: Additional error details, when present. type: array items: type: object additionalProperties: true PwsErrorCause: description: A single request validation failure. type: object required: - field - message properties: field: description: Dot-notation path to the offending request field. type: string message: description: Human-readable explanation of the failed validation rule. type: string PwsErrorBase: description: Common fields present on every PWS API error object. type: object required: - type - status - instance - code properties: type: description: Machine-readable error class. type: string status: description: HTTP status code returned for this error. type: integer format: int32 instance: description: Request identifier for this specific error occurrence. type: string code: description: Stable machine-readable error code. type: string doc_url: description: Optional link to documentation for this error. type: string format: uri headers: TraceId: description: Trace identifier for the request. Include it when contacting support. schema: type: string example: 4bf92f3577b34da6a3ce929d0e0e4736 StrictTransportSecurity: description: Enforces HTTPS for the duration specified by `max-age`. schema: type: string example: max-age=31536000; includeSubDomains; preload CacheControl: description: Prevents caching of sensitive financial data. Always `no-store`. schema: type: string enum: - no-store example: no-store responses: RampBadRequestResponse: description: Validation error headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/BadRequestError' examples: bad-request: value: error: type: validation_error status: 400 instance: req_123 code: bad_request RampUnauthenticatedResponse: description: Authentication required headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedError' examples: unauthenticated: value: error: type: authentication_error status: 401 instance: req_123 code: unauthenticated RampForbiddenResponse: description: Forbidden headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' examples: forbidden: value: error: type: authorization_error status: 403 instance: req_123 code: forbidden RampResourceExhaustedResponse: description: Rate limit exceeded headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/ResourceExhaustedError' examples: resource-exhausted: value: error: type: rate_limit_error status: 429 instance: req_123 code: resource_exhausted RampInternalResponse: description: Internal server error headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/InternalError' examples: internal-error: value: error: type: internal_error status: 500 instance: req_123 code: internal RampUnimplementedResponse: description: Not implemented headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/UnimplementedError' examples: unimplemented: value: error: type: api_error status: 501 instance: req_123 code: unimplemented RampUnavailableResponse: description: Service unavailable headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/UnavailableError' examples: unavailable: value: error: type: service_error status: 503 instance: req_123 code: unavailable RampDeadlineExceededResponse: description: Deadline exceeded headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/DeadlineExceededError' examples: deadline-exceeded: value: error: type: service_error status: 504 instance: req_123 code: deadline_exceeded securitySchemes: ApiKey: type: apiKey in: header name: API-Key description: Your public API key. Identifies the partner making the request. ApiSign: type: apiKey in: header name: API-Sign description: HMAC signature over the request, computed with your private key. ApiNonce: type: apiKey in: header name: API-Nonce description: Monotonically increasing nonce included in the request signature. ````