> ## Documentation Index > Fetch the complete documentation index at: https://docs.wava.co/llms.txt > Use this file to discover all available pages before exploring further. # Create direct order > Create and process a payment order directly. The API initiates payment processing immediately based on the selected gateway. **All direct API orders require** `id_number` and `id_type` in the shopper object for compliance and buyer identification, regardless of the selected gateway. Use the Get Document Types endpoint to retrieve valid `id_type` values. **Gateway-specific behavior:** **Nequi** — Additionally requires `phone_number` in the shopper object. A push notification is sent to the buyer's Nequi app. The buyer approves or rejects in-app. You receive a webhook when the payment is confirmed or cancelled. **Daviplata** — Uses `id_number` and `id_type` to initiate the OTP flow. Only accepts CC, CE, and TI document types. The buyer receives an OTP via SMS. You must submit the OTP using the Daviplata OTP endpoint to complete payment. **Breb** — Uses `id_number` and `id_type` to generate a transfer. Only accepts CC, CE, and TI document types. The API returns a QR code (base64 encoded) and a transfer key. The buyer uses either to complete the interbank transfer via their banking app. You receive a webhook when the payment is confirmed. The `id_payment_gateway` value must come from the Get Payment Gateways endpoint. Do not hardcode gateway IDs as they may vary by store configuration. ## OpenAPI ````yaml /api-reference/openapi.yaml post /orders openapi: 3.0.3 info: title: Wava Public API description: > # Wava API Documentation Wava Technologies provides a unified payment processing platform for Colombian and Latin American digital payment methods. This documentation covers all integration options available to merchants and partners. ## Integration Options | Method | Description | Best For | |--------|-------------|----------| | **Direct API** | Full control over payment flow | Custom checkout experiences | | **Payment Links** | Shareable URLs for payment collection | Quick invoicing, social selling | | **Dynamic Links** | Payment links without fixed amount | Donations, tips, variable pricing | | **Partners API** | Manage stores and process payments on their behalf | Platforms, aggregators, resellers | | **E-commerce Plugins** | Pre-built integrations | Tiendanube, WooCommerce stores | | **Stripe Connect** | Card payments via connected Stripe accounts | Merchants wanting card acceptance | ## Authentication All API requests require authentication via a merchant key in the request header: ``` merchant-key: YOUR_MERCHANT_KEY ``` Partner API requests additionally require two headers for two-factor authentication: ``` X-API-Key: YOUR_PARTNER_API_KEY X-API-Secret: YOUR_PARTNER_SECRET_KEY ``` Contact Wava support to obtain your credentials and configure your store for API access. ## Environments | Environment | Base URL | Purpose | |------------|----------|---------| | **Production** | `https://api.wava.co/v1` | Live transactions | | **Development** | `https://api.dev.wava.co/v1` | Testing and development | ## Supported Payment Methods | Gateway | Description | Currency | Requirements | Flow | |---------|-------------|----------|--------------|------| | **Nequi** | Mobile wallet | COP | Phone number + National ID | Push notification approval | | **Daviplata** | Digital wallet | COP | National ID + Document type (CC, CE, TI only) | SMS OTP verification | | **Breb (Bre-B)** | Interbank transfer | COP | National ID + Document type (CC, CE, TI only) | QR code / transfer key | | **Stripe** | Card payments | Multiple | Connected Stripe account | Card form (not available via Direct API) | **Note:** All direct API orders require `id_number` and `id_type` in the shopper object, regardless of the payment gateway. This is required for compliance and buyer identification. The API also accepts `national_id_number` and `id_national_document_type` as aliases. ## Changes from v1 - **New gateway: Breb** — Interbank transfers via QR code or transfer key - **Payment Links API** — Create shareable payment URLs programmatically - **Dynamic Links** — Payment links where the buyer enters the amount - **Partners API** — Platform partners can operate on behalf of onboarded stores - **Simplified field names**: `id_number` and `id_type` are the recommended shopper fields. Legacy names `national_id_number` and `id_national_document_type` are still accepted as aliases. version: 2.0.0 contact: name: Wava API Support email: soporte@wava.co url: https://wava.co/contacto servers: - url: https://api.wava.co/v1 description: Production server - url: https://api.dev.wava.co/v1 description: Development server security: - MerchantKeyAuth: [] tags: - name: Payment Gateways description: > Discover available payment methods for your store. Use these endpoints to determine which gateways are active, their requirements, and supported currencies. Call this endpoint before creating orders to dynamically build your payment form based on each gateway's requirements. - name: Orders description: > Create and manage payment orders with direct API processing. This is the core integration for merchants who want full control over the checkout experience. **Supported flows:** - **Nequi**: Push notification → buyer approves in app → webhook confirmation - **Daviplata**: Order created → SMS OTP sent → submit OTP → confirmation - **Breb**: Order created → QR code + transfer key returned → buyer completes transfer → webhook confirmation **Order lifecycle:** `pending` → `processing` → `confirmed` / `cancelled` / `refunded` **Important:** All direct API orders require `id_number` and `id_type` in the shopper object for compliance purposes, regardless of the payment gateway. - name: Links description: > Create shareable payment URLs that redirect buyers to a hosted checkout page. Payment links are ideal for invoicing, social media selling, or any scenario where you want to collect payment without building a custom checkout. **Payment link types:** - **Standard link**: Fixed amount — buyer selects payment method and completes payment - **Dynamic link**: No fixed amount — buyer enters the amount before paying. Create by omitting the `amount` field. Links are accessed by buyers at `https://checkout.wava.co/{hash}`. - name: Partners description: > The Partners API allows approved platform partners to manage stores and process payments on their behalf. Partners can onboard merchants, create orders and payment links, and access transaction data for their portfolio of stores. **Authentication**: Partners include both the `X-API-Key` and `X-API-Secret` headers (partner two-factor authentication) plus the `merchant-key` (store identification). The partner credentials authenticate the partner, and the merchant key identifies which store the operation is for. Contact Wava to apply for partner access. - name: Utilities description: > Helper endpoints that provide reference data needed for payment processing, such as document types by country. Use these to build localized payment forms. - name: Integrations description: > Pre-built integrations for e-commerce platforms and third-party services. **Available integrations:** - **Tiendanube**: Automatic payment processing for Tiendanube stores - **WooCommerce**: WordPress plugin for WooCommerce checkout - **Stripe Connect**: Accept card payments through a connected Stripe account See the dedicated guide for each integration for setup instructions and configuration. externalDocs: description: Full Documentation Portal url: https://docs.wava.co paths: /orders: post: tags: - Orders summary: Create direct order description: > Create and process a payment order directly. The API initiates payment processing immediately based on the selected gateway. **All direct API orders require** `id_number` and `id_type` in the shopper object for compliance and buyer identification, regardless of the selected gateway. Use the Get Document Types endpoint to retrieve valid `id_type` values. **Gateway-specific behavior:** **Nequi** — Additionally requires `phone_number` in the shopper object. A push notification is sent to the buyer's Nequi app. The buyer approves or rejects in-app. You receive a webhook when the payment is confirmed or cancelled. **Daviplata** — Uses `id_number` and `id_type` to initiate the OTP flow. Only accepts CC, CE, and TI document types. The buyer receives an OTP via SMS. You must submit the OTP using the Daviplata OTP endpoint to complete payment. **Breb** — Uses `id_number` and `id_type` to generate a transfer. Only accepts CC, CE, and TI document types. The API returns a QR code (base64 encoded) and a transfer key. The buyer uses either to complete the interbank transfer via their banking app. You receive a webhook when the payment is confirmed. The `id_payment_gateway` value must come from the Get Payment Gateways endpoint. Do not hardcode gateway IDs as they may vary by store configuration. operationId: createOrder requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateDirectOrderRequest' examples: nequi_order: summary: Nequi payment order description: >- Buyer receives push notification in Nequi app. National ID fields are required for compliance. value: amount: 50000 description: Premium subscription - Monthly currency: COP shopper: first_name: Juan last_name: Pérez email: juan.perez@email.com phone_number: '+573001234567' country: CO id_number: '1234567890' id_type: 1 payment_gateway: id_payment_gateway: 1 order_key: order-12345 redirect_link: https://mystore.com/success redirect_link_cancel: https://mystore.com/cancel redirect_link_failure: https://mystore.com/error daviplata_order: summary: Daviplata payment order description: >- Buyer receives OTP via SMS. Only CC, CE, TI document types accepted. value: amount: 75000 description: Product purchase - XYZ Item currency: COP shopper: first_name: María last_name: González email: maria.gonzalez@email.com phone_number: '+573001234567' country: CO id_number: '12345678' id_type: 1 payment_gateway: id_payment_gateway: 2 order_key: order-67890 redirect_link: https://mystore.com/success breb_order: summary: Breb interbank transfer order description: >- Returns QR code and transfer key for the buyer. Only CC, CE, TI document types accepted. value: amount: 100000 description: 'Invoice #1234 - Consulting services' currency: COP shopper: first_name: Carlos last_name: Rodríguez email: carlos.rodriguez@email.com phone_number: '+573009876543' country: CO id_number: '87654321' id_type: 1 payment_gateway: id_payment_gateway: 9 order_key: order-breb-001 redirect_link: https://mystore.com/success responses: '200': description: Order created and payment initiated successfully content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/OrderProcessingResponse' examples: nequi_processing: summary: Nequi — push notification sent value: data: id_order: 12345 status: processing payment_gateway: nequi: phone_number: '****567' daviplata_processing: summary: Daviplata — OTP required value: data: id_order: 12346 status: processing daviplata_token_required: true payment_gateway: daviplata: national_id_number: '****678' id_national_document_type: 1 id_type: CC breb_processing: summary: Breb — QR code and transfer key value: data: id_order: 12347 status: processing payment_gateway: breb: qr_code: iVBORw0KGgoAAAANSUhEUgAA...(base64 encoded QR image) key: BREB-TRX-2025-ABC123DEF456 '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalServerError' components: schemas: CreateDirectOrderRequest: type: object required: - amount - description - payment_gateway properties: amount: type: number minimum: 0.01 description: Order amount. Must be greater than 0. example: 50000 description: type: string minLength: 1 maxLength: 255 description: Order description displayed to the buyer during checkout. example: Premium subscription - Monthly currency: type: string minLength: 3 maxLength: 3 pattern: ^[A-Z]{3}$ description: ISO 4217 currency code. Defaults to store currency if omitted. example: COP shopper: $ref: '#/components/schemas/ShopperInfo' payment_gateway: $ref: '#/components/schemas/PaymentGatewayInfo' order_key: type: string maxLength: 100 description: >- Your external order reference. Use this to correlate Wava orders with your system. example: order-12345 redirect_link: type: string format: uri description: URL to redirect buyer after successful payment. example: https://mystore.com/success redirect_link_cancel: type: string format: uri description: URL to redirect buyer if payment is cancelled. example: https://mystore.com/cancel redirect_link_failure: type: string format: uri description: URL to redirect buyer if payment fails. example: https://mystore.com/error device_key: type: string maxLength: 100 description: Device identifier for session tracking. example: device-12345 OrderProcessingResponse: type: object properties: id_order: type: integer description: >- Unique order ID. Use this for all subsequent operations (status check, cancel, refund). example: 12345 status: type: string enum: - processing description: Order status. Will be `processing` while awaiting buyer action. example: processing daviplata_token_required: type: boolean description: >- Present and `true` only for Daviplata orders. Submit the OTP via the Daviplata OTP endpoint. example: true payment_gateway: type: object description: >- Gateway-specific response data. The key name varies by gateway (nequi, daviplata, breb). oneOf: - $ref: '#/components/schemas/NequiPaymentInfo' - $ref: '#/components/schemas/DaviplataPaymentInfo' - $ref: '#/components/schemas/BrebPaymentInfo' ShopperInfo: type: object required: - email - phone_number - country - id_number - id_type properties: first_name: type: string maxLength: 50 description: Buyer's first name. example: Juan last_name: type: string maxLength: 50 description: Buyer's last name. example: Pérez email: type: string format: email description: Buyer's email address. Required for all orders. example: juan.perez@email.com phone_number: type: string pattern: ^\+?[\d\s\-\(\)]+$ description: >- Buyer's phone number. Required for all orders. For Nequi payments, this is the number that receives the push notification. example: '+573001234567' country: type: string pattern: ^[A-Z]{2}$ description: Two-letter ISO country code. Required for all orders. example: CO id_number: type: string maxLength: 50 description: >- Buyer's national ID number (cedula). Required for all direct API orders for compliance. Also used by Daviplata and Breb to initiate payment. Alias `national_id_number` is also accepted. example: '12345678' id_type: type: integer minimum: 1 description: >- Document type ID from the Get Document Types endpoint. Required for all direct API orders. Use `GET /national-document-types/CO` to get valid values (e.g. 1 for CC). Alias `id_national_document_type` is also accepted. example: 1 PaymentGatewayInfo: type: object required: - id_payment_gateway properties: id_payment_gateway: type: integer minimum: 1 description: >- Gateway ID obtained from the Get Payment Gateways endpoint. Do not hardcode this value. example: 1 NequiPaymentInfo: type: object properties: nequi: type: object properties: phone_number: type: string description: Masked phone number that received the push notification. example: '****567' DaviplataPaymentInfo: type: object properties: daviplata: type: object properties: national_id_number: type: string description: Masked national ID. example: '****678' id_national_document_type: type: integer description: Document type ID. example: 1 id_type: type: string description: Document type code. example: CC BrebPaymentInfo: type: object properties: breb: type: object properties: qr_code: type: string description: >- Base64-encoded QR code image. Display to the buyer for scanning with their banking app. example: iVBORw0KGgoAAAANSUhEUgAA... key: type: string description: >- Transfer key (party identifier). Alternative to QR code for completing the interbank transfer. example: BREB-TRX-2025-ABC123DEF456 ErrorResponse: type: object required: - code - message - error properties: code: type: integer description: Numeric error code grouped by category. See Error Codes section. example: 4001 api_code: type: string description: Machine-readable error identifier. example: PAYMENT_GATEWAY_REQUIRED message: type: string description: Human-readable error message. example: Payment gateway is required description: type: string description: Detailed explanation and resolution guidance. example: A payment gateway must be specified to process the order error: type: boolean example: true gateway_name: type: string description: Relevant payment gateway (included in gateway-specific errors). example: Nequi provided_currency: type: string description: Currency provided in request (included in currency errors). example: USD supported_currency: type: string description: Expected currency (included in currency errors). example: COP validation_errors: type: array description: Field-level validation errors. items: type: object properties: field: type: string example: phone_number message: type: string example: Phone number is required for Nequi payments responses: ValidationError: description: Request validation failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_amount: summary: Missing required field value: code: 2000 api_code: VALIDATION_FAILED message: Validation failed description: One or more required fields are missing or invalid error: true validation_errors: - field: amount message: Amount is required missing_national_id: summary: Missing national ID fields value: code: 2000 api_code: VALIDATION_FAILED message: Validation failed description: National ID fields are required for all direct API orders error: true validation_errors: - field: shopper message: Either id_number or national_id_number is required invalid_phone: summary: Invalid phone number for Nequi value: code: 4005 api_code: PAYMENT_GATEWAY_VALIDATION_FAILED message: Phone number is required for Nequi payments description: Nequi payments require a valid Colombian phone number error: true gateway_name: Nequi Unauthorized: description: Authentication required or invalid credentials content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_merchant_key: summary: Invalid merchant key value: code: 4007 api_code: INVALID_MERCHANT_KEY message: Invalid merchant key description: The provided merchant key is invalid or expired error: true InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: code: 7001 api_code: INTERNAL_SERVER_ERROR message: Internal server error description: An unexpected error occurred while processing your request error: true securitySchemes: MerchantKeyAuth: type: apiKey in: header name: merchant-key description: | Merchant key for store identification. Required for all API requests. ``` merchant-key: YOUR_MERCHANT_KEY ``` ````