> ## 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. # Get Ramp checkout URL > Generate a hosted Ramp checkout URL for the provided transaction configuration. The response echoes the request parameters so the Ramp partner can confirm what was submitted. ## OpenAPI ````yaml https://d2588n1sy4m36o.cloudfront.net/uat/merged/openapi.json get /v1/ramp/checkout 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/ramp/checkout: get: tags: - Ramp summary: Get Ramp checkout URL description: >- Generate a hosted Ramp checkout URL for the provided transaction configuration. The response echoes the request parameters so the Ramp partner can confirm what was submitted. operationId: getRampCheckout parameters: - in: query name: from_symbol schema: $ref: '#/components/schemas/AssetSymbol' style: form description: >- Source asset ticker symbol (e.g., "USD"). Use `GET /v1/ramp/fiat-currencies` to discover supported source currencies. example: USD required: true - in: query name: from_type schema: $ref: '#/components/schemas/Ramp_SourceAssetType' style: form description: >- Classification of the source asset. Pair with `from_symbol` to disambiguate when the same ticker exists across asset classes (e.g., `USDC` as `stablecoin` vs `crypto`). Only fiat sources are currently supported (on-ramp). example: fiat - in: query name: from_method schema: type: string minLength: 1 maxLength: 128 style: form description: >- Funding method used for the source side. Use `GET /v1/ramp/payment-methods` to discover supported payment methods. example: credit_card required: true - in: query name: from_amount schema: type: string pattern: ^[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 style: form description: >- Amount to spend, denominated in the source asset, as a decimal string. example: '100.00' required: true - in: query name: to_symbol schema: $ref: '#/components/schemas/AssetSymbol' style: form description: >- Destination asset ticker symbol (e.g., "BTC"). Use `GET /v1/ramp/buy/crypto` to discover supported destination assets. example: BTC required: true - in: query name: to_type schema: $ref: '#/components/schemas/Ramp_DestinationAssetType' style: form description: >- Classification of the destination asset. Pair with `to_symbol` to disambiguate when the same ticker exists across asset classes (e.g., `USDC` as `stablecoin` vs `crypto`). Only crypto and stablecoin destinations are currently supported (on-ramp). example: crypto - in: query name: to_method schema: type: string minLength: 1 maxLength: 128 style: form description: >- Withdrawal method for the destination asset. Use `GET /v1/ramp/buy/crypto` to discover available withdrawal methods for each asset. example: Bitcoin required: true - in: query name: to_network schema: type: string minLength: 1 maxLength: 128 style: form description: >- Optional withdrawal network identifier. Use `GET /v1/ramp/buy/crypto` to discover available networks for each destination asset. example: Bitcoin - in: query name: to_address schema: type: string minLength: 1 maxLength: 512 style: form description: Optional destination wallet address for the crypto withdrawal. example: bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh - in: query name: to_memo schema: type: string minLength: 1 maxLength: 256 style: form description: >- Optional memo/tag/note for the crypto withdrawal (used for certain assets). example: '123456' - in: query name: affiliate_fee_bps schema: type: string pattern: ^(10000|[0-9]{1,4})$ minLength: 1 maxLength: 5 style: form description: >- Affiliate fee in basis points to attribute to the partner (0-10000 where 100 = 1%). This fee is additive to the platform fee, increasing the total fee charged to the user. The affiliate_fee in webhook payloads reflects the partner's portion of the total fee for transactions originating from this checkout. example: '250' - in: query name: country schema: type: string pattern: ^[A-Za-z]{2}$ minLength: 2 maxLength: 2 style: form description: >- ISO 3166-1 alpha-2 country code. Use `GET /v1/ramp/countries` to discover supported values. example: US required: true - in: query name: subdivision schema: type: string pattern: ^[A-Za-z0-9-]+$ minLength: 1 maxLength: 64 style: form 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. example: CA - in: query name: redirect_url schema: type: string minLength: 1 maxLength: 255 style: form description: URL to redirect the user after completing checkout successfully. example: https://example.com/checkout/success - in: query name: failure_url schema: type: string minLength: 1 maxLength: 255 style: form description: URL to redirect the user after a failed checkout. example: https://example.com/checkout/failure - in: query name: external_user_id schema: type: string minLength: 1 maxLength: 64 style: form description: Optional partner-supplied user identifier. example: user_123 - in: query name: external_partner_id schema: type: string minLength: 1 maxLength: 64 style: form description: Optional partner-supplied partner identifier. example: partner_456 - in: query name: external_transaction_id schema: type: string minLength: 1 maxLength: 64 style: form description: Optional partner transaction identifier. example: txn_789 - in: query name: external_metadata schema: type: string minLength: 1 maxLength: 1000 style: form description: Optional metadata to store alongside the checkout. example: campaign=spring 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: Checkout details for the requested Ramp route. type: object properties: checkout_url: description: Hosted checkout URL. type: string minLength: 1 maxLength: 2048 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: RampCheckoutData required: - checkout_url required: - data examples: checkout: summary: Hosted checkout URL value: data: checkout_url: https://checkout.ramp.network/?session=checkout-123 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_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: 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 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. ````