openapi: 3.1.0 info: title: Weav API version: 1.0.0-draft summary: Accept payments in the Philippines with one integration. description: | The Weav merchant API. Create payments on one channel (QR Ph, GCash, Pay with Maya, cards, and over-the-counter partners), track them, and read your balance, ledger and withdrawals. - **Base URL:** `https://api.weavpayments.com` (paths start with `/v1`). - **Auth:** send your API key as a Bearer token. `wv_test_` keys use test mode, `wv_live_` keys use live mode. - **Money:** JSON numbers in the currency's major unit (e.g. `1250.00` PHP). Never strings. - **Times:** ISO 8601 with offset, Asia/Manila (`+08:00`). - **Envelope:** every response is `{ code, success, message, data }`; errors add `errors` for field problems. - **Retries are safe:** on `POST /v1/payments` and `POST /v1/checkouts`, the same `external_reference_id` and body returns the stored response instead of creating another. Send an `Idempotency-Key` header (such as a UUID) to use your own key instead. - **Pagination:** cursor based (`cursor`, `per_page` up to 100). There's no total count; stop when `is_last_page` is true. This is a draft for review. Response codes and some endpoints are proposed and may change before general availability. contact: name: Weav support email: support@weavpayments.com url: https://docs.weavpayments.com servers: - url: https://api.weavpayments.com description: Production (live and test keys) security: - apiKey: [] tags: - name: Checkouts description: The quickest way to get paid. One link for an order or an amount; your customer chooses how to pay on Weav's page. - name: Payments description: Create a payment on one channel, then follow it to a final status. - name: Payment methods description: Save a customer's card once, then charge it with no payer present (auto-debit, subscriptions). - name: Balance description: Your available balance, what's on hold, and every change to it. - name: Withdrawals description: Transfers from your balance to your payout account. Created in the dashboard. - name: Channels description: Which payment channels your account can use right now. - name: Webhooks description: Your webhook URL, the events Weav sends to it, and reposting them. paths: /v1/checkouts: get: tags: [Checkouts] operationId: listCheckouts summary: List checkouts parameters: - { $ref: '#/components/parameters/PerPage' } - { $ref: '#/components/parameters/Cursor' } - { $ref: '#/components/parameters/DateFrom' } - { $ref: '#/components/parameters/DateTo' } - name: status in: query description: Only checkouts with this status. `OPEN`, `COMPLETED`, `EXPIRED` or `CANCELLED`. schema: { $ref: '#/components/schemas/CheckoutStatus' } - name: external_reference_id in: query schema: { type: string, maxLength: 64 } responses: '200': description: Your checkouts in this mode, newest first. content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: data: type: object properties: checkouts: { type: array, items: { $ref: '#/components/schemas/Checkout', }, } pagination: { $ref: '#/components/schemas/Pagination', } examples: default: value: code: '2000000' success: true message: 'OK' data: checkouts: - reference_id: 'CK4T8M2Q7X9KBA' external_reference_id: 'ORD-10541' type: 'ORDER' status: 'COMPLETED' currency: 'PHP' amount: 1250.0 description: null items: - name: 'Canvas tote bag' quantity: 1 unit_amount: 1000.0 amount: 1000.0 - name: 'Canvas Strap' quantity: 2 unit_amount: 125.0 amount: 250.0 channels: null qr_ph_apps: null customer: id: null name: null email: null mobile_no: null save_payment_method: false checkout_url: 'https://pay.weavpayments.com/checkout/CK4T8M2Q7X9KBA' success_url: 'https://shop.example.com/orders/ORD-10541/thanks' cancel_url: 'https://shop.example.com/cart' webhook_url: null payment: reference_id: 'PY7K3Q9M2X4TBA' checkout_reference_id: 'CK4T8M2Q7X9KBA' status: 'COMPLETED' '…': '…' expires_at: '2026-10-27T10:12:00+08:00' completed_at: '2026-10-26T10:15:40+08:00' expired_at: null cancelled_at: null created_at: '2026-10-26T10:12:00+08:00' updated_at: '2026-10-26T10:15:41+08:00' pagination: per_page: 25 next_cursor: 'eyJpZCI6MTM0LCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9' prev_cursor: null is_last_page: false '401': { $ref: '#/components/responses/Unauthenticated' } '403': { $ref: '#/components/responses/Forbidden' } post: tags: [Checkouts] operationId: createCheckout summary: Create a checkout description: | One call, one link. Send your customer to `checkout_url`: they choose how to pay (QR Ph, e-wallets, cards or cash at a counter), give their name if you didn't, and pay. Paid once. Send `items` (Weav adds them up) or one `amount`, never both. Each channel your customer starts is a payment with `checkout_reference_id` set (its PAYMENT_* webhooks still come). The first payment paid completes the checkout (`CHECKOUT_COMPLETED`). Never treat a redirect to `success_url` as proof of payment. parameters: - name: Idempotency-Key in: header required: false description: Optional. A unique value per new checkout, such as a UUID. Retrying with the same key and body returns the stored response; a different body returns 409. Without it, your `external_reference_id` is the key (a checkout with neither is never matched to an earlier one). schema: { type: string, maxLength: 255 } requestBody: required: true content: application/json: schema: { $ref: '#/components/schemas/CreateCheckout' } examples: order: summary: 'An order' value: items: - name: 'Canvas tote bag' quantity: 1 unit_amount: 1000.00 - name: 'Canvas Strap' quantity: 2 unit_amount: 125.00 external_reference_id: 'ORD-10541' success_url: 'https://shop.example.com/orders/ORD-10541/thanks' cancel_url: 'https://shop.example.com/cart' save-card: summary: 'A plan, saving the card' value: items: - name: 'Monthly plan' quantity: 1 unit_amount: 499.00 external_reference_id: 'SUB-USER-123-START' channels: ['CARD'] save_payment_method: true customer: id: 'USER-123' name: 'Juan dela Cruz' success_url: 'https://shop.example.com/account/plan' responses: '201': description: Checkout created (code 2010300). content: application/json: schema: allOf: - $ref: '#/components/schemas/CheckoutResponse' - type: object properties: code: type: string const: '2010300' example: '2010300' message: type: string const: Checkout created example: Checkout created examples: order: summary: 'An order' value: code: '2010300' success: true message: 'Checkout created' data: checkout: reference_id: 'CK4T8M2Q7X9KBA' external_reference_id: 'ORD-10541' type: 'ORDER' status: 'OPEN' currency: 'PHP' amount: 1250.0 description: null items: - name: 'Canvas tote bag' quantity: 1 unit_amount: 1000.0 amount: 1000.0 - name: 'Canvas Strap' quantity: 2 unit_amount: 125.0 amount: 250.0 channels: null qr_ph_apps: null customer: id: null name: null email: null mobile_no: null save_payment_method: false checkout_url: 'https://pay.weavpayments.com/checkout/CK4T8M2Q7X9KBA' success_url: 'https://shop.example.com/orders/ORD-10541/thanks' cancel_url: 'https://shop.example.com/cart' webhook_url: null payment: null expires_at: '2026-10-27T10:12:00+08:00' completed_at: null expired_at: null cancelled_at: null created_at: '2026-10-26T10:12:00+08:00' updated_at: '2026-10-26T10:12:00+08:00' '401': { $ref: '#/components/responses/Unauthenticated' } '403': { $ref: '#/components/responses/Forbidden' } '409': { $ref: '#/components/responses/Conflict' } '422': { $ref: '#/components/responses/ValidationFailed' } '429': { $ref: '#/components/responses/TooManyRequests' } /v1/checkouts/{reference_id}: get: tags: [Checkouts] operationId: retrieveCheckout summary: Retrieve a checkout parameters: - { name: reference_id, in: path, required: true, schema: { type: string, example: CK4T8M2Q7X9KBA }, } responses: '200': description: The checkout. content: application/json: schema: { $ref: '#/components/schemas/CheckoutResponse', } examples: default: value: code: '2000000' success: true message: 'OK' data: checkout: reference_id: 'CK4T8M2Q7X9KBA' external_reference_id: 'ORD-10541' type: 'ORDER' status: 'COMPLETED' currency: 'PHP' amount: 1250.0 description: null items: - name: 'Canvas tote bag' quantity: 1 unit_amount: 1000.0 amount: 1000.0 - name: 'Canvas Strap' quantity: 2 unit_amount: 125.0 amount: 250.0 channels: null qr_ph_apps: null customer: id: null name: null email: null mobile_no: null save_payment_method: false checkout_url: 'https://pay.weavpayments.com/checkout/CK4T8M2Q7X9KBA' success_url: 'https://shop.example.com/orders/ORD-10541/thanks' cancel_url: 'https://shop.example.com/cart' webhook_url: null payment: reference_id: 'PY7K3Q9M2X4TBA' checkout_reference_id: 'CK4T8M2Q7X9KBA' status: 'COMPLETED' '…': '…' expires_at: '2026-10-27T10:12:00+08:00' completed_at: '2026-10-26T10:15:40+08:00' expired_at: null cancelled_at: null created_at: '2026-10-26T10:12:00+08:00' updated_at: '2026-10-26T10:15:41+08:00' '401': { $ref: '#/components/responses/Unauthenticated' } '403': { $ref: '#/components/responses/Forbidden' } '404': { $ref: '#/components/responses/NotFound' } /v1/checkouts/{reference_id}/cancel: post: tags: [Checkouts] operationId: cancelCheckout summary: Cancel a checkout description: Cancels an `OPEN` checkout, and the payment in progress with it. 409 `4090301` when it isn't open; 409 `4090302` when the provider can't cancel the payment in progress yet (retry shortly). parameters: - { name: reference_id, in: path, required: true, schema: { type: string, example: CK4T8M2Q7X9KBA }, } responses: '200': description: Checkout canceled (code 2000301). content: application/json: schema: allOf: - $ref: '#/components/schemas/CheckoutResponse' - type: object properties: code: type: string const: '2000301' example: '2000301' message: type: string const: Checkout canceled example: Checkout canceled examples: default: value: code: '2000301' success: true message: 'Checkout canceled' data: checkout: reference_id: 'CK4T8M2Q7X9KBA' external_reference_id: 'ORD-10541' type: 'ORDER' status: 'CANCELLED' currency: 'PHP' amount: 1250.0 description: null items: - name: 'Canvas tote bag' quantity: 1 unit_amount: 1000.0 amount: 1000.0 - name: 'Canvas Strap' quantity: 2 unit_amount: 125.0 amount: 250.0 channels: null qr_ph_apps: null customer: id: null name: null email: null mobile_no: null save_payment_method: false checkout_url: 'https://pay.weavpayments.com/checkout/CK4T8M2Q7X9KBA' success_url: 'https://shop.example.com/orders/ORD-10541/thanks' cancel_url: 'https://shop.example.com/cart' webhook_url: null payment: null expires_at: '2026-10-27T10:12:00+08:00' completed_at: null expired_at: null cancelled_at: '2026-10-26T11:02:00+08:00' created_at: '2026-10-26T10:12:00+08:00' updated_at: '2026-10-26T11:02:00+08:00' '401': { $ref: '#/components/responses/Unauthenticated' } '403': { $ref: '#/components/responses/Forbidden' } '404': { $ref: '#/components/responses/NotFound' } '409': { $ref: '#/components/responses/Conflict' } /v1/payments: get: tags: [Payments] operationId: listPayments summary: List payments description: Newest first. Filter by status, channel, your reference or creation date. parameters: - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/DateFrom' - $ref: '#/components/parameters/DateTo' - name: status in: query description: Only payments with this status. schema: { $ref: '#/components/schemas/PaymentStatus' } - name: channel in: query description: Only payments on this channel. schema: { $ref: '#/components/schemas/Channel' } - name: external_reference_id in: query description: Your own order or invoice reference, exact match. schema: { type: string, maxLength: 64 } - name: reference in: query description: Exact match on `reference_id`, `provider_reference_id` or `channel_reference_id`, or a number in references (for example the QR Ph invoice number your customer gives you). A number in references can match more than one payment. schema: { type: string, maxLength: 64 } - name: payment_method_id in: query description: Only the payments charged to this saved payment method, or saving it. A subscription's history. schema: { type: string, maxLength: 32 } example: PM8K2Q7X9KBAT4MZ3N responses: '200': description: A page of payments. content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: data: type: object required: [payments, pagination] properties: payments: { type: array, items: { $ref: '#/components/schemas/Payment', }, } pagination: { $ref: '#/components/schemas/Pagination', } examples: default: value: code: '2000000' success: true message: 'OK' data: payments: - reference_id: 'PY7K3Q9M2X4TBA' external_reference_id: 'ORD-10541' channel: 'QR_PH' currency: 'PHP' amount: 1250.0 status: 'COMPLETED' completed_at: '2026-10-26T10:15:40+08:00' created_at: '2026-10-26T10:12:00+08:00' pagination: per_page: 25 next_cursor: 'eyJpZCI6MTM0LCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9' prev_cursor: null is_last_page: false '401': { $ref: '#/components/responses/Unauthenticated' } '403': { $ref: '#/components/responses/Forbidden' } '422': { $ref: '#/components/responses/ValidationFailed' } '429': { $ref: '#/components/responses/TooManyRequests' } post: tags: [Payments] operationId: createPayment summary: Create a payment description: | Creates a payment on one channel and returns what the customer does next (`next_action`): scan a QR code, go to a checkout page, or pay at a counter with a payment code. With a test key, the checkout page is Weav's test checkout, where you pay, decline or expire the payment. Live payments run through the providers. parameters: - name: Idempotency-Key in: header required: false description: Optional. A unique value per new payment, such as a UUID. Retrying with the same key and body returns the stored response; a different body returns 409. Without it, your `external_reference_id` is the key. schema: { type: string, maxLength: 255 } example: 7d1f6c0e-2b4a-4c9e-9f3d-6a1b8e2c5f10 requestBody: required: true content: application/json: schema: { $ref: '#/components/schemas/CreatePayment' } examples: qrph: summary: 'QR Ph' value: channel: 'QR_PH' currency: 'PHP' amount: 1250.00 external_reference_id: 'ORD-10541' description: 'Order ORD-10541' next_action_format: 'DIRECT' customer: name: 'Juan dela Cruz' email: null mobile_no: null gcash: summary: 'GCash' value: channel: 'GCASH' currency: 'PHP' amount: 1250.00 external_reference_id: 'ORD-10542' description: 'Order ORD-10542' customer: name: 'Juan dela Cruz' email: null mobile_no: null success_url: 'https://shop.example/orders/10542/done' cancel_url: 'https://shop.example/orders/10542/retry' saved-card: summary: 'A saved card (auto-debit)' value: payment_method_id: 'PM8K2Q7X9KBAT4MZ3N' currency: 'PHP' amount: 499.00 external_reference_id: 'SUB-USER-123-2026-11' description: 'November plan' pay-and-save: summary: 'Pay by card and save it' value: channel: 'CARD' currency: 'PHP' amount: 499.00 external_reference_id: 'SUB-USER-123-2026-10' description: 'October plan' save_payment_method: true customer: id: 'USER-123' name: 'Juan dela Cruz' email: 'juan@example.com' success_url: 'https://shop.example/account/plan' cancel_url: 'https://shop.example/account/plan' pay-and-go: summary: 'Pay & Go' value: channel: 'PAY_AND_GO' currency: 'PHP' amount: 3500.00 external_reference_id: 'ORD-10543' description: null next_action_format: 'DIRECT' customer: name: 'Juan dela Cruz' email: null mobile_no: null responses: '201': description: Payment created (code 2010100). content: application/json: schema: allOf: - $ref: '#/components/schemas/PaymentResponse' - type: object properties: code: type: string const: '2010100' example: '2010100' message: type: string const: Payment created example: Payment created examples: qrph: summary: 'QR Ph' value: code: '2010100' success: true message: 'Payment created' data: payment: reference_id: 'PY7K3Q9M2X4TBA' external_reference_id: 'ORD-10541' checkout_reference_id: null payment_method_id: null provider_reference_id: null channel_reference_id: null references: {} channel: 'QR_PH' customer: name: 'Juan dela Cruz' email: null mobile_no: null currency: 'PHP' amount: 1250.0 fee: 31.25 total: 1281.25 fee_bearer: 'MERCHANT' amount_charged: 1250.0 amount_refunded: 0.0 refunds: [] status: 'PENDING' description: 'Order ORD-10541' success_url: null cancel_url: null webhook_url: null next_action: type: 'DISPLAY_QR' qr_string: '00020101021228…6304A1B2' checkout_url: null payment_code: null qr_ph_app: null instructions: - title: 'Open your bank or e-wallet app' description: 'Any app that supports QR Ph works.' - title: 'Scan the QR code' description: "Use the app's QR scanner on the code on your screen, or upload a saved copy." - title: 'Confirm the payment' description: "Check the amount and the merchant's name, then confirm." test_checkout_url: null failure: null expires_at: '2026-10-26T10:27:00+08:00' completed_at: null failed_at: null cancelled_at: null reversed_at: null created_at: '2026-10-26T10:12:00+08:00' updated_at: '2026-10-26T10:12:00+08:00' gcash: summary: 'GCash' value: code: '2010100' success: true message: 'Payment created' data: payment: reference_id: 'PY3T8N1W6R2QCD' external_reference_id: 'ORD-10542' checkout_reference_id: null payment_method_id: null provider_reference_id: null channel_reference_id: null references: {} channel: 'GCASH' customer: name: 'Juan dela Cruz' email: null mobile_no: null currency: 'PHP' amount: 1250.0 fee: 31.25 total: 1281.25 fee_bearer: 'MERCHANT' amount_charged: 1250.0 amount_refunded: 0.0 refunds: [] status: 'PENDING' description: 'Order ORD-10542' success_url: 'https://shop.example/orders/10542/done' cancel_url: 'https://shop.example/orders/10542/retry' webhook_url: null next_action: type: 'REDIRECT' qr_string: null checkout_url: 'https://pay.weavpayments.com/pay/PY3T8N1W6R2QCD' payment_code: null qr_ph_app: null instructions: null test_checkout_url: null failure: null expires_at: '2026-10-27T10:12:00+08:00' completed_at: null failed_at: null cancelled_at: null reversed_at: null created_at: '2026-10-26T10:12:00+08:00' updated_at: '2026-10-26T10:12:00+08:00' pay-and-go: summary: 'Pay & Go' value: code: '2010100' success: true message: 'Payment created' data: payment: reference_id: 'PY9M4C2X7K1VHE' external_reference_id: 'ORD-10543' checkout_reference_id: null payment_method_id: null provider_reference_id: null channel_reference_id: null references: {} channel: 'PAY_AND_GO' customer: name: 'Juan dela Cruz' email: null mobile_no: null currency: 'PHP' amount: 3500.0 fee: 87.5 total: 3587.5 fee_bearer: 'MERCHANT' amount_charged: 3500.0 amount_refunded: 0.0 refunds: [] status: 'PENDING' description: null success_url: null cancel_url: null webhook_url: null next_action: type: 'PAY_AT_COUNTER' qr_string: null checkout_url: null payment_code: 'EP7K2M4Q9X1TB3A' qr_ph_app: null instructions: null test_checkout_url: null failure: null expires_at: '2026-10-28T10:12:00+08:00' completed_at: null failed_at: null cancelled_at: null reversed_at: null created_at: '2026-10-26T10:12:00+08:00' updated_at: '2026-10-26T10:12:00+08:00' '401': { $ref: '#/components/responses/Unauthenticated' } '403': { $ref: '#/components/responses/Forbidden' } '409': { $ref: '#/components/responses/Conflict' } '422': { $ref: '#/components/responses/ValidationFailed' } '429': { $ref: '#/components/responses/TooManyRequests' } '501': { $ref: '#/components/responses/NotAvailableYet' } /v1/payments/{reference_id}: get: tags: [Payments] operationId: retrievePayment summary: Retrieve a payment parameters: [{ $ref: '#/components/parameters/PaymentReference' }] responses: '200': description: The payment. content: application/json: schema: { $ref: '#/components/schemas/PaymentResponse' } examples: default: value: code: '2000000' success: true message: 'OK' data: payment: reference_id: 'PY7K3Q9M2X4TBA' external_reference_id: 'ORD-10541' checkout_reference_id: null payment_method_id: null provider_reference_id: null channel_reference_id: null references: {} channel: 'QR_PH' customer: name: 'Juan dela Cruz' email: null mobile_no: null currency: 'PHP' amount: 1250.0 fee: 31.25 total: 1281.25 fee_bearer: 'MERCHANT' amount_charged: 1250.0 amount_refunded: 0.0 refunds: [] status: 'COMPLETED' description: 'Order ORD-10541' success_url: null cancel_url: null webhook_url: null next_action: type: null qr_string: null checkout_url: null payment_code: null qr_ph_app: null instructions: null test_checkout_url: null failure: null expires_at: '2026-10-26T10:27:00+08:00' completed_at: '2026-10-26T10:15:40+08:00' failed_at: null cancelled_at: null reversed_at: null created_at: '2026-10-26T10:12:00+08:00' updated_at: '2026-10-26T10:15:41+08:00' '401': { $ref: '#/components/responses/Unauthenticated' } '403': { $ref: '#/components/responses/Forbidden' } '404': { $ref: '#/components/responses/NotFound' } /v1/payments/{reference_id}/cancel: post: tags: [Payments] operationId: cancelPayment summary: Cancel a payment description: Cancels a payment that's still `PENDING`, so the customer can no longer pay it. Proposed. parameters: [{ $ref: '#/components/parameters/PaymentReference' }] responses: '200': description: Payment canceled (code 2000101). content: application/json: schema: allOf: - $ref: '#/components/schemas/PaymentResponse' - type: object properties: code: type: string const: '2000101' example: '2000101' message: type: string const: Payment canceled example: Payment canceled examples: default: value: code: '2000101' success: true message: 'Payment canceled' data: payment: reference_id: 'PY9M4C2X7K1VHE' external_reference_id: 'ORD-10543' checkout_reference_id: null payment_method_id: null provider_reference_id: null channel_reference_id: null references: {} channel: 'PAY_AND_GO' customer: name: 'Juan dela Cruz' email: null mobile_no: null currency: 'PHP' amount: 3500.0 fee: 87.5 total: 3587.5 fee_bearer: 'MERCHANT' amount_charged: 3500.0 amount_refunded: 0.0 refunds: [] status: 'CANCELLED' description: null success_url: null cancel_url: null webhook_url: null next_action: type: null qr_string: null checkout_url: null payment_code: null qr_ph_app: null instructions: null test_checkout_url: null failure: null expires_at: '2026-10-28T10:12:00+08:00' completed_at: null failed_at: null cancelled_at: '2026-10-26T11:02:00+08:00' reversed_at: null created_at: '2026-10-26T10:12:00+08:00' updated_at: '2026-10-26T11:02:00+08:00' '401': { $ref: '#/components/responses/Unauthenticated' } '403': { $ref: '#/components/responses/Forbidden' } '404': { $ref: '#/components/responses/NotFound' } '409': description: The payment isn't pending, so it can't be canceled (code 4090101), or the provider can't cancel it yet (code 4090102, retry shortly). content: application/json: schema: { $ref: '#/components/schemas/Error' } examples: default: value: code: '4090101' success: false message: 'Only a pending payment can be canceled.' '501': { $ref: '#/components/responses/NotAvailableYet' } /v1/payments/{reference_id}/webhooks/repost: post: tags: [Webhooks] operationId: repostPaymentWebhook summary: Repost a payment's latest webhook description: Sends the payment's latest webhook again, to your current webhook URL, signed with your active key and a fresh `sent_at`. Only finished deliveries can be reposted. Once every 30 seconds per payment (4290201) and up to 20 a minute per account (4290202), API and dashboard together; to check a status, retrieve the payment instead. Proposed. parameters: [{ $ref: '#/components/parameters/PaymentReference' }] responses: '202': description: Queued for repost (code 2020200). content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: code: type: string const: '2020200' example: '2020200' message: type: string const: Webhook queued for repost example: Webhook queued for repost data: type: object properties: event: { $ref: '#/components/schemas/WebhookEventName', } reference_id: { type: string, example: PY7K3Q9M2X4TBA, } examples: default: value: code: '2020200' success: true message: 'Webhook queued for repost' data: event: 'PAYMENT_COMPLETED' reference_id: 'PY7K3Q9M2X4TBA' '401': { $ref: '#/components/responses/Unauthenticated' } '403': { $ref: '#/components/responses/Forbidden' } '404': { $ref: '#/components/responses/NotFound' } '409': { $ref: '#/components/responses/Conflict' } '429': { $ref: '#/components/responses/TooManyRequests' } /v1/payment-methods: get: tags: [Payment methods] operationId: listPaymentMethods summary: List saved payment methods description: Newest first. Filter by your customer's ID to show their saved cards. parameters: - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/DateFrom' - $ref: '#/components/parameters/DateTo' - name: customer_id in: query description: Your own ID for the customer, exact match. schema: { type: string, maxLength: 64 } - name: status in: query schema: { $ref: '#/components/schemas/PaymentMethodStatus' } - name: expires_by in: query description: Only cards that expire in this month or earlier (`YYYY-MM`). Run it each month to ask those customers for a new card. schema: { type: string, pattern: '^\d{4}-\d{2}$' } example: '2026-12' responses: '200': description: A page of saved payment methods. content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: data: type: object properties: payment_methods: { type: array, items: { $ref: '#/components/schemas/PaymentMethod', }, } pagination: { $ref: '#/components/schemas/Pagination', } examples: default: value: code: '2000000' success: true message: 'OK' data: payment_methods: - id: 'PM8K2Q7X9KBAT4MZ3N' type: 'CARD' status: 'ACTIVE' customer: { id: 'USER-123', name: 'Juan dela Cruz', email: 'juan@example.com', } card: { brand: 'VISA', last4: '1381', exp_month: 12, exp_year: 2030, } label: 'Visa •••• 1381' '…': '…' pagination: per_page: 25 next_cursor: null prev_cursor: null is_last_page: true '401': { $ref: '#/components/responses/Unauthenticated' } '403': { $ref: '#/components/responses/Forbidden' } '422': { $ref: '#/components/responses/ValidationFailed' } post: tags: [Payment methods] operationId: createPaymentMethod summary: Save a payment method description: | Saves a customer's card for later charges with no payer present (auto-debit, subscriptions). Send your customer to `next_action.checkout_url`: Weav's save page, where they type their card, agree to future charges and confirm it with their bank (3DS). Their bank may show a ₱10.00 check that is canceled right after. The card goes from their browser to the card processor; it never reaches Weav or you. You get `PAYMENT_METHOD_SAVED` (now `ACTIVE`: charge it with `POST /v1/payments` and its `payment_method_id`) or `PAYMENT_METHOD_FAILED`. A link not used within 24 hours fails. Only cards today (`type: CARD`). Saving cards is off until Weav turns it on for your account with your PCI DSS evidence (422 `4220401`); in test mode it always works, with a test save page. requestBody: required: true content: application/json: schema: { $ref: '#/components/schemas/CreatePaymentMethod' } examples: default: value: type: 'CARD' customer: id: 'USER-123' name: 'Juan dela Cruz' email: 'juan@example.com' success_url: 'https://shop.example/account/cards' cancel_url: 'https://shop.example/account' responses: '201': description: Payment method created (code 2010400). content: application/json: schema: { $ref: '#/components/schemas/PaymentMethodResponse', } examples: default: value: code: '2010400' success: true message: 'Payment method created' data: payment_method: id: 'PM8K2Q7X9KBAT4MZ3N' type: 'CARD' status: 'PENDING' customer: id: 'USER-123' name: 'Juan dela Cruz' email: 'juan@example.com' card: null label: null next_action: type: 'REDIRECT' checkout_url: 'https://pay.weavpayments.com/save/PM8K2Q7X9KBAT4MZ3N' success_url: 'https://shop.example/account/cards' cancel_url: 'https://shop.example/account' webhook_url: null expires_at: '2026-11-03T10:12:00+08:00' activated_at: null failed_at: null removed_at: null created_at: '2026-11-02T10:12:00+08:00' updated_at: '2026-11-02T10:12:00+08:00' '401': { $ref: '#/components/responses/Unauthenticated' } '403': { $ref: '#/components/responses/Forbidden' } '422': description: Invalid fields, or saving cards is off for your account (4220401). content: application/json: schema: { $ref: '#/components/schemas/Error' } example: code: '4220401' success: false message: 'Saving cards is off for your account.' errors: type: [ 'Contact support@weavpayments.com to turn it on. Weav needs your PCI DSS evidence first.', ] /v1/payment-methods/{id}: get: tags: [Payment methods] operationId: retrievePaymentMethod summary: Retrieve a payment method parameters: - { name: id, in: path, required: true, schema: { type: string, example: PM8K2Q7X9KBAT4MZ3N }, } responses: '200': description: The payment method. content: application/json: schema: { $ref: '#/components/schemas/PaymentMethodResponse', } examples: default: value: code: '2000000' success: true message: 'OK' data: payment_method: id: 'PM8K2Q7X9KBAT4MZ3N' type: 'CARD' status: 'ACTIVE' customer: id: 'USER-123' name: 'Juan dela Cruz' email: 'juan@example.com' card: { brand: 'VISA', last4: '1381', exp_month: 12, exp_year: 2030, } label: 'Visa •••• 1381' next_action: type: null checkout_url: null success_url: 'https://shop.example/account/cards' cancel_url: 'https://shop.example/account' webhook_url: null expires_at: null activated_at: '2026-11-02T10:14:20+08:00' failed_at: null removed_at: null created_at: '2026-11-02T10:12:00+08:00' updated_at: '2026-11-02T10:14:20+08:00' '401': { $ref: '#/components/responses/Unauthenticated' } '403': { $ref: '#/components/responses/Forbidden' } '404': { $ref: '#/components/responses/NotFound' } delete: tags: [Payment methods] operationId: removePaymentMethod summary: Remove a payment method description: Removes the card at the card processor too, so nobody can charge it again (`PAYMENT_METHOD_REMOVED`). Removing one already removed is fine. 409 `4090401` when the processor can't remove it right now (retry shortly). parameters: - { name: id, in: path, required: true, schema: { type: string, example: PM8K2Q7X9KBAT4MZ3N }, } responses: '200': description: Payment method removed (code 2000401). content: application/json: schema: { $ref: '#/components/schemas/PaymentMethodResponse', } examples: default: value: code: '2000401' success: true message: 'Payment method removed' data: payment_method: id: 'PM8K2Q7X9KBAT4MZ3N' type: 'CARD' status: 'REMOVED' customer: id: 'USER-123' name: 'Juan dela Cruz' email: 'juan@example.com' card: { brand: 'VISA', last4: '1381', exp_month: 12, exp_year: 2030, } label: 'Visa •••• 1381' next_action: type: null checkout_url: null success_url: 'https://shop.example/account/cards' cancel_url: 'https://shop.example/account' webhook_url: null expires_at: null activated_at: '2026-11-02T10:14:20+08:00' failed_at: null removed_at: '2026-11-20T09:00:00+08:00' created_at: '2026-11-02T10:12:00+08:00' updated_at: '2026-11-20T09:00:00+08:00' '401': { $ref: '#/components/responses/Unauthenticated' } '403': { $ref: '#/components/responses/Forbidden' } '404': { $ref: '#/components/responses/NotFound' } '409': { $ref: '#/components/responses/Conflict' } /v1/balance: get: tags: [Balance] operationId: getBalance summary: Get your balance parameters: - name: currency in: query description: Defaults to your account's default currency. schema: { $ref: '#/components/schemas/Currency' } responses: '200': description: Your balance in one currency. content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: data: type: object properties: balance: { $ref: '#/components/schemas/Balance', } examples: default: value: code: '2000000' success: true message: 'OK' data: balance: currency: 'PHP' available: 64835.17 on_hold: 119000.0 as_of: '2026-10-26T10:15:40+08:00' '401': { $ref: '#/components/responses/Unauthenticated' } '403': { $ref: '#/components/responses/Forbidden' } '422': { $ref: '#/components/responses/ValidationFailed' } /v1/ledger-entries: get: tags: [Balance] operationId: listLedgerEntries summary: List ledger entries description: Every change to your available balance, newest first. parameters: - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/DateFrom' - $ref: '#/components/parameters/DateTo' - name: type in: query description: Only entries of this type. schema: { $ref: '#/components/schemas/LedgerEntryType' } responses: '200': description: A page of ledger entries. content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: data: type: object properties: ledger_entries: { type: array, items: { $ref: '#/components/schemas/LedgerEntry', }, } pagination: { $ref: '#/components/schemas/Pagination', } examples: default: value: code: '2000000' success: true message: 'OK' data: ledger_entries: - reference_id: 'LE5Q2W8E4R6T1Y' type: 'PAYMENT' currency: 'PHP' amount: 1250.0 balance_after: 64835.17 source: type: 'PAYMENT' reference_id: 'PY7K3Q9M2X4TBA' description: null posted_at: '2026-10-26T10:15:40+08:00' pagination: per_page: 25 next_cursor: null prev_cursor: null is_last_page: true '401': { $ref: '#/components/responses/Unauthenticated' } '403': { $ref: '#/components/responses/Forbidden' } /v1/withdrawals: get: tags: [Withdrawals] operationId: listWithdrawals summary: List withdrawals parameters: - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/DateFrom' - $ref: '#/components/parameters/DateTo' - in: query name: reference description: Exact match on `reference_id`, `provider_reference_id` or `channel_reference_id`. schema: { type: string, maxLength: 64 } responses: '200': description: A page of withdrawals. content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: data: type: object properties: withdrawals: { type: array, items: { $ref: '#/components/schemas/Withdrawal', }, } pagination: { $ref: '#/components/schemas/Pagination', } examples: default: value: code: '2000000' success: true message: 'OK' data: withdrawals: - reference_id: 'WD2H6J9K3L7M4N' currency: 'PHP' amount: 119000.0 fee: 10.0 total: 119010.0 status: 'FOR_SETTLEMENT' rail: 'PESONET' provider_reference_id: null channel_reference_id: null destination: bank_name: 'Sample Bank' account_name: 'Sample Store Inc.' account_number_last4: '4821' failure: null requested_at: '2026-10-25T14:05:00+08:00' completed_at: null failed_at: null updated_at: '2026-10-25T14:30:00+08:00' pagination: per_page: 25 next_cursor: 'eyJpZCI6MTM0LCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9' prev_cursor: null is_last_page: false '401': { $ref: '#/components/responses/Unauthenticated' } '403': { $ref: '#/components/responses/Forbidden' } /v1/withdrawals/{reference_id}: get: tags: [Withdrawals] operationId: retrieveWithdrawal summary: Retrieve a withdrawal parameters: - name: reference_id in: path required: true schema: { type: string, pattern: '^WD[0-9A-Z]{12}$', example: WD8H2K4M6P9QRT, } responses: '200': description: The withdrawal. content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: data: type: object properties: withdrawal: { $ref: '#/components/schemas/Withdrawal', } examples: default: value: code: '2000000' success: true message: 'OK' data: withdrawal: reference_id: 'WD2H6J9K3L7M4N' currency: 'PHP' amount: 119000.0 fee: 10.0 total: 119010.0 status: 'FOR_SETTLEMENT' rail: 'PESONET' provider_reference_id: null channel_reference_id: null destination: bank_name: 'Sample Bank' account_name: 'Sample Store Inc.' account_number_last4: '4821' failure: null requested_at: '2026-10-25T14:05:00+08:00' completed_at: null failed_at: null updated_at: '2026-10-25T14:30:00+08:00' '401': { $ref: '#/components/responses/Unauthenticated' } '403': { $ref: '#/components/responses/Forbidden' } '404': { $ref: '#/components/responses/NotFound' } /v1/channels: get: tags: [Channels] operationId: listChannels summary: List channels description: Every channel and whether your account can use it now (allowed by Weav and switched on by you). responses: '200': description: All channels. content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: data: type: object properties: payment_limits: type: array description: The smallest and largest payment you can create, per currency. Null means no limit. items: type: object properties: currency: { $ref: '#/components/schemas/Currency', } min_amount: { type: [ number, 'null', ], example: 0.01, } max_amount: { type: [ number, 'null', ], example: 50000.00, } channels: { type: array, items: { $ref: '#/components/schemas/ChannelStatus', }, } examples: default: value: code: '2000000' success: true message: 'OK' data: payment_limits: - currency: 'PHP' min_amount: 0.01 max_amount: 50000.0 channels: - channel: 'QR_PH' name: 'QR Ph' is_enabled: true apps: - code: 'BDO' name: 'BDO Pay' - code: 'CHINABANK' name: 'Chinabank' - code: 'GOTYME' name: 'GoTyme' - code: 'LANDBANK' name: 'LANDBANK' - code: 'METROBANK' name: 'Metrobank' - code: 'PNB' name: 'PNB' - code: 'RCBC' name: 'RCBC' - code: 'ROBINSONS_BANK' name: 'Robinsons Bank' - code: 'SECURITY_BANK' name: 'Security Bank' - code: 'UNIONBANK' name: 'UnionBank' - code: 'GRABPAY' name: 'GrabPay' - code: 'SHOPEEPAY' name: 'ShopeePay' maintenance: null - channel: 'GCASH' name: 'GCash' is_enabled: true apps: [] maintenance: null - channel: 'MAYA' name: 'Pay with Maya' is_enabled: true apps: [] maintenance: null - channel: 'CARD' name: 'Credit or debit card' is_enabled: false apps: [] maintenance: null - channel: 'PAY_AND_GO' name: 'Pay & Go' is_enabled: true apps: [] maintenance: null - channel: 'PALAWANPAY' name: 'PalawanPay' is_enabled: true apps: [] maintenance: null - channel: 'BAYAD' name: 'Bayad' is_enabled: true apps: [] maintenance: null '401': { $ref: '#/components/responses/Unauthenticated' } '403': { $ref: '#/components/responses/Forbidden' } /v1/webhook-endpoint: get: tags: [Webhooks] operationId: getWebhookEndpoint summary: Get your webhook URL description: The one URL where Weav sends this mode's webhooks (payments and withdrawals). responses: '200': description: Your webhook endpoint. content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: data: type: object properties: webhook_endpoint: { $ref: '#/components/schemas/WebhookEndpoint', } examples: default: value: code: '2000000' success: true message: 'OK' data: webhook_endpoint: url: 'https://example.com/webhooks/weav' events: - 'PAYMENT_COMPLETED' - 'PAYMENT_FAILED' - 'PAYMENT_CANCELLED' - 'PAYMENT_REVERSED' - 'PAYMENT_REFUNDED' - 'CHECKOUT_COMPLETED' - 'CHECKOUT_EXPIRED' - 'WITHDRAWAL_COMPLETED' - 'WITHDRAWAL_FAILED' withdrawals_url: null health: 'UNKNOWN' has_signing_key: true last_success_at: null updated_at: '2026-10-26T10:00:00+08:00' '401': { $ref: '#/components/responses/Unauthenticated' } '403': { $ref: '#/components/responses/Forbidden' } '404': { $ref: '#/components/responses/NotFound' } put: tags: [Webhooks] operationId: setWebhookEndpoint summary: Set your webhook URL description: | Sets or replaces this mode's webhook URL, and optionally a separate URL for withdrawal events. They can only be set here, not in the dashboard, so nobody changes them by accident; every change is emailed to your Owners and Developers. Each webhook goes to exactly one URL: a payment's own `webhook_url` if it has one, else `withdrawals_url` for withdrawal events when set, else url (limited to events). The URL must be public HTTPS: private and internal addresses are refused. Webhooks are signed with the signing key you create in the dashboard, and none are sent until one exists (`has_signing_key`). requestBody: required: true content: application/json: schema: type: object required: [url] properties: url: type: string format: uri maxLength: 2048 example: 'https://example.com/webhooks/weav' description: Required. A public HTTPS URL, up to 2,048 characters. Its host must resolve. Private and internal addresses (such as `localhost` or `10.x`) are refused. events: type: array description: Which events url gets. Leave out for all of them. Doesn't limit `withdrawals_url` or a payment's `webhook_url`. items: $ref: '#/components/schemas/WebhookEventName' withdrawals_url: type: [string, 'null'] maxLength: 2048 description: Optional. Withdrawal events go here instead of url (url stops getting them). Null removes it; leaving it out keeps it. responses: '200': description: Saved (code 2000000). content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: message: type: string const: Webhook endpoint saved example: Webhook endpoint saved data: type: object properties: webhook_endpoint: { $ref: '#/components/schemas/WebhookEndpoint', } examples: default: value: code: '2000000' success: true message: 'Webhook endpoint saved' data: webhook_endpoint: url: 'https://example.com/webhooks/weav' events: - 'PAYMENT_COMPLETED' - 'PAYMENT_FAILED' - 'PAYMENT_CANCELLED' - 'PAYMENT_REVERSED' - 'PAYMENT_REFUNDED' - 'CHECKOUT_COMPLETED' - 'CHECKOUT_EXPIRED' - 'WITHDRAWAL_COMPLETED' - 'WITHDRAWAL_FAILED' withdrawals_url: null health: 'UNKNOWN' has_signing_key: true last_success_at: null updated_at: '2026-10-26T10:00:00+08:00' '401': { $ref: '#/components/responses/Unauthenticated' } '403': { $ref: '#/components/responses/Forbidden' } '422': { $ref: '#/components/responses/ValidationFailed' } delete: tags: [Webhooks] operationId: removeWebhookEndpoint summary: Remove your webhook URL description: Stops this mode's webhooks until a URL is set again. responses: '200': description: Removed (code 2000000). The withdrawals URL, if set, is removed too. content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: message: type: string const: Webhook endpoint removed example: Webhook endpoint removed data: type: object properties: webhook_endpoint: type: 'null' examples: default: value: code: '2000000' success: true message: 'Webhook endpoint removed' data: webhook_endpoint: null '401': { $ref: '#/components/responses/Unauthenticated' } '403': { $ref: '#/components/responses/Forbidden' } '404': { $ref: '#/components/responses/NotFound' } webhooks: paymentEvent: post: tags: [Webhooks] operationId: receivePaymentEvent summary: Payment event (sent to your webhook URL) description: | Weav POSTs JSON to your HTTPS webhook URL when a payment or withdrawal reaches a final status. **Verify first:** `X-Signature` is the HMAC-SHA512 of the raw request body with your signing key, in lowercase hex. Compare in constant time, then reject deliveries whose `sent_at` is more than 5 minutes old. **Reply fast:** answer `2xx` within 10 seconds, then do the work in a queue. Anything else is a failed attempt. Failed deliveries retry 17 times over about 7 days (2m, 10m, 10m, 1h, 2h, 6h, then every 15h, with up to 10% jitter). `Retry-After` on 429 or 503 is honored. Redirects aren't followed. The same event can arrive more than once: handle it idempotently. parameters: - name: X-Signature in: header required: true description: HMAC-SHA512 of the raw body, lowercase hex. schema: { type: string, pattern: '^[0-9a-f]{128}$' } requestBody: required: true content: application/json: schema: { $ref: '#/components/schemas/WebhookPayload' } responses: '200': description: Received. Any 2xx counts. components: securitySchemes: apiKey: type: http scheme: bearer bearerFormat: wv_live_… or wv_test_… description: An API key from Developers in the dashboard. The prefix sets the mode. Keys can be limited to an IP allowlist. parameters: PaymentReference: name: reference_id in: path required: true description: Weav's payment reference. schema: { type: string, pattern: '^PY[0-9A-Z]{12}$', example: PY7K3Q9M2X4TBA, } PerPage: name: per_page in: query description: Items per page, 25 by default; values above 100 become 100. schema: { type: integer, minimum: 1, default: 25 } Cursor: name: cursor in: query description: The `next_cursor` or `prev_cursor` from the previous page. schema: { type: string, maxLength: 1024 } DateFrom: name: date_from in: query description: Start date (Asia/Manila), inclusive. Send with `date_to`. schema: { type: string, format: date } DateTo: name: date_to in: query description: End date (Asia/Manila), inclusive. schema: { type: string, format: date } responses: Unauthenticated: description: Missing, malformed or unknown API key (code 4010000). content: application/json: schema: { $ref: '#/components/schemas/Error' } example: code: '4010000' success: false message: 'Missing or invalid API key.' Forbidden: description: "The key can't make this request (code 4030000): an address outside the key's IP allowlist, a live key before your live mode is on, or an account that isn't active. A live key sent from a browser is refused (code 4030001): keep live keys on your server." content: application/json: schema: { $ref: '#/components/schemas/Error' } example: code: '4030000' success: false message: 'Requests with this key must come from an address on its allowlist.' NotFound: description: Not found in this mode for your account (code 4040000). content: application/json: schema: { $ref: '#/components/schemas/Error' } example: code: '4040000' success: false message: 'Not found.' Conflict: description: The request conflicts with the current state, e.g. an Idempotency-Key reused with a different body (4090001), a request still in progress (4090002), a payment that can't be canceled (4090101) or can't be canceled at the provider yet (4090102, retry shortly), or a webhook still being sent (4090201). content: application/json: schema: { $ref: '#/components/schemas/Error' } example: code: '4090001' success: false message: 'This Idempotency-Key was already used with a different request.' ValidationFailed: description: One or more fields are invalid (code 4220000), or the channel is off (4220101) or doesn't take the currency (4220102). content: application/json: schema: { $ref: '#/components/schemas/Error' } example: code: '4220000' success: false message: 'The given data was invalid.' errors: channel: - 'The channel field is required.' TooManyRequests: description: Rate limited (code 4290000). Wait for `Retry-After` seconds. headers: Retry-After: { schema: { type: integer } } content: application/json: schema: { $ref: '#/components/schemas/Error' } example: code: '4290000' success: false message: 'Too many requests. Wait, then retry.' NotAvailableYet: description: "This channel isn't live for your account yet (code 5010100); use a test key." content: application/json: schema: { $ref: '#/components/schemas/Error' } example: code: '5010100' success: false message: "Live payments aren't available through the API yet. Use a test key, or contact support@weavpayments.com." schemas: WebhookEndpoint: type: object properties: url: { type: string, example: 'https://example.com/webhooks/weav', } events: { type: array, items: { type: string } } health: { type: string, enum: [UNKNOWN, HEALTHY, FAILING, DOWN] } withdrawals_url: type: [string, 'null'] description: Where withdrawal events go, when not url. has_signing_key: { type: boolean, description: 'Webhooks go out only once a signing key exists. Create it in the dashboard under Developers.', } last_success_at: { type: [string, 'null'], format: date-time } updated_at: { type: [string, 'null'], format: date-time } Envelope: type: object required: [code, success, message, data] properties: code: { type: string, description: '7 digits: HTTP status, service, case. 2000000 for most requests; each response that uses another code says so.', example: '2000000', } success: { type: boolean, example: true } message: { type: string, example: OK } data: { type: object } Error: type: object required: [code, success, message] properties: code: { type: string, example: '4220000', description: "7 digits: HTTP status, service, case. Each response lists its codes. Any request can also get 4000000 (the body isn't valid JSON) or 5000000 (something went wrong at Weav: retry the same request).", } success: { type: boolean, const: false } message: { type: string, example: Validation failed } errors: type: object description: Field name to a list of messages. additionalProperties: { type: array, items: { type: string } } example: { amount: ['The amount must be greater than 0.'] } Pagination: type: object required: [per_page, next_cursor, prev_cursor, is_last_page] properties: per_page: { type: integer, example: 25 } next_cursor: { type: [string, 'null'] } prev_cursor: { type: [string, 'null'] } is_last_page: { type: boolean } Channel: type: string enum: [QR_PH, GCASH, MAYA, CARD, PAY_AND_GO, PALAWANPAY, BAYAD] description: '`QR_PH` (any bank or e-wallet), `GCASH`, `MAYA` (Pay with Maya), `CARD` (Maya Checkout), `PAY_AND_GO`, `PALAWANPAY` and `BAYAD` (pay at a counter).' Currency: type: string description: ISO 4217. PHP today; more as they're enabled for your account. enum: [PHP] example: PHP PaymentStatus: type: string enum: [PENDING, COMPLETED, FAILED, CANCELLED, REVERSED, REFUNDED] CreatePayment: type: object required: [currency, amount, external_reference_id] properties: channel: $ref: '#/components/schemas/Channel' description: Required, unless you send `payment_method_id`. One of `QR_PH`, `GCASH`, `MAYA`, `CARD`, `PAY_AND_GO`, `PALAWANPAY`, `BAYAD`. The channel must be on for your account, or the response is 422 (4220101). payment_method_id: type: [string, 'null'] description: Charge a saved payment method instead (auto-debit), with no payer present. Leave out `channel` and `customer`. Only an `ACTIVE` one, or 422 `4220103`. A card is usually paid at once (`COMPLETED`); if the bank asks your customer to confirm again, it's `PENDING` with `next_action.type` `REDIRECT`. example: PM8K2Q7X9KBAT4MZ3N save_payment_method: type: [boolean, 'null'] description: "`CARD` only. Also saves your customer's card for later charges (auto-debit), so you don't need `POST /v1/payment-methods` first. Send `customer.id`. On Weav's payment page, your customer agrees to future charges and pays; their bank's check (3DS) for this payment also confirms the card. The response's `payment_method_id` is the new method, `PENDING` until the payment is paid. You get `PAYMENT_COMPLETED`, then `PAYMENT_METHOD_SAVED`. If the payment isn't paid, the card isn't kept (`PAYMENT_METHOD_FAILED`). Off until Weav turns on saving cards for your account (422 `4220401`)." example: true currency: { $ref: '#/components/schemas/Currency' } amount: { type: number, exclusiveMinimum: 0, description: "Major unit, up to the currency's decimals (2 for PHP). Must be within your payment limits (GET /v1/channels; by default ₱0.01 to ₱50,000.00), or the response is 422.", example: 1250.00, } external_reference_id: { type: string, maxLength: 64, description: 'Your order or invoice reference. Unique across your payments in this mode (test and live are separate); reusing one returns 422.', example: ORDER-10541, } description: type: [string, 'null'] maxLength: 255 description: Up to 255 characters. Your customer sees it on their emailed receipt (sent when you give their email). next_action_format: type: [string, 'null'] enum: [HOSTED, DIRECT, null] description: "`HOSTED` (default, every channel) returns `next_action.checkout_url`, Weav's payment page; the payment is set up with the provider when the customer opens it. `DIRECT` sets it up right away and returns the raw `qr_string` (with instructions), the provider's `checkout_url` or the `payment_code`." qr_ph_app: type: [string, 'null'] enum: [ BDO, CHINABANK, GOTYME, LANDBANK, METROBANK, PNB, RCBC, ROBINSONS_BANK, SECURITY_BANK, UNIONBANK, GRABPAY, SHOPEEPAY, null, ] description: QR Ph only. Tailors the how-to-pay steps to one bank or e-wallet app; any QR Ph app can still pay. customer: type: [object, 'null'] description: The person paying. Stored encrypted; with an email, Weav emails them a receipt once the payment is paid. Weav needs the name for every payment (anti-money-laundering and fraud checks). Leave it out with `HOSTED` and Weav's payment page asks your customer before they pay; with `DIRECT` there's no Weav page, so `name` is required. properties: id: { type: string, maxLength: 64, pattern: '^[A-Za-z0-9._:@-]+$', example: USER-123, description: 'With `save_payment_method` only, and required then: your own ID for this customer. Their saved cards are listed by it (`GET /v1/payment-methods?customer_id=`).', } name: { type: string, maxLength: 255, example: Juan dela Cruz, description: One field; not split into first and last name., } email: { type: [string, 'null'], format: email, maxLength: 255, } mobile_no: { type: [string, 'null'], maxLength: 20, example: '09171234567', description: A Philippine mobile number., } webhook_url: type: [string, 'null'] maxLength: 2048 description: Optional. All of this payment's webhooks go here instead of your webhook URL, whatever its events list says. Public HTTPS only, signed with your signing key. success_url: type: [string, 'null'] format: uri maxLength: 2048 description: Optional, HTTPS. Where your customer goes once the payment is paid. Without it, they stay on Weav's result page. Never treat this redirect as proof of payment. cancel_url: type: [string, 'null'] format: uri maxLength: 2048 description: Optional, HTTPS. Where your customer goes if they leave without paying (the payment failed, expired or was canceled). Without it, they stay on Weav's result page. NextAction: type: object properties: type: { type: [string, 'null'], enum: [DISPLAY_QR, REDIRECT, PAY_AT_COUNTER, null], } qr_string: { type: [string, 'null'], description: 'QR Ph payload to render as a QR code: error correction Q (M at minimum), a white quiet zone of at least 4 modules, and the full-color QR Ph symbol on a white box 23.81% of the code width (quiet zone excluded) in the exact center.', } checkout_url: { type: [string, 'null'], format: uri } payment_code: { type: [string, 'null'], description: For over-the-counter channels., } qr_ph_app: { type: [string, 'null'], description: QR Ph only. The bank or e-wallet app the steps are tailored to., } instructions: type: [array, 'null'] description: QR Ph with `next_action_format` `DIRECT` only. How-to-pay steps to show the customer. items: type: object properties: title: { type: string, example: Open BDO Pay } description: { type: string } Payment: type: object properties: reference_id: { type: string, example: PY7K3Q9M2X4TBA } external_reference_id: { type: [string, 'null'], example: ORDER-10541, description: "Yours. For a checkout's payment, the checkout's (null when it has none).", } checkout_reference_id: { type: [string, 'null'], description: 'The checkout this payment was started from, if any.', } payment_method_id: { type: [string, 'null'], description: 'The saved payment method it was charged to, or the one it saves the card to (`save_payment_method`), if any.', } provider_reference_id: { type: [string, 'null'], description: "The provider's transaction ID, once the provider has one.", } channel_reference_id: { type: [string, 'null'], description: 'A reference from the channel that is unique to this payment, once the payment completes. Null for channels whose numbers can repeat; those are in references.', } references: { type: object, description: "The provider's other numbers for this payment, keyed by type: `invoice_number` (the 6-digit QR Ph invoice number), `receipt_number` (Maya) or `transaction_id` (GCash). Saved once the provider confirms the payment; {} until then. They can repeat across payments: search with them, never identify a payment by one alone.", properties: { invoice_number: { type: string, example: '372465' }, receipt_number: { type: string }, transaction_id: { type: string }, }, additionalProperties: false, } channel: $ref: '#/components/schemas/Channel' description: One of `QR_PH`, `GCASH`, `MAYA`, `CARD`, `PAY_AND_GO`, `PALAWANPAY`, `BAYAD`. customer: type: object description: The person paying, as you sent it. The email and mobile number turn null once Weav's retention period ends. properties: name: type: [string, 'null'] example: Juan dela Cruz email: { type: [string, 'null'] } mobile_no: { type: [string, 'null'] } currency: { $ref: '#/components/schemas/Currency' } amount: { type: number, example: 1250.00 } fee: { type: [number, 'null'], description: Null until a rate applies., } total: type: [number, 'null'] description: '`amount` plus `fee`, calculated by Weav. Null while `fee` is null.' fee_bearer: type: string enum: [MERCHANT, PAYER] description: '`MERCHANT`, the fee comes out of `amount` (default). `PAYER` (fees on top), the customer is charged `amount` + `fee` and you receive the full `amount`.' amount_charged: type: number description: What the customer is charged. `amount`, or `total` when `fee_bearer` is `PAYER`. amount_refunded: { type: number, example: 0, description: 'The total refunded so far. The payment turns `REFUNDED` once it equals `amount`.', } refunds: type: array description: Refunds Weav recorded for this payment, oldest first. Refunds are made by Weav support on request. items: type: object properties: reference_id: { type: string, example: RF8M2KQ7X4TB1C } amount: { type: number, example: 250.00 } provider_reference_id: { type: [string, 'null'] } refunded_at: { type: string, format: date-time } status: $ref: '#/components/schemas/PaymentStatus' description: '`PENDING`, `COMPLETED`, `FAILED`, `CANCELLED`, `REVERSED` or `REFUNDED`. See [Statuses](/statuses).' description: type: [string, 'null'] description: As you sent it. success_url: { type: [string, 'null'], format: uri } cancel_url: { type: [string, 'null'], format: uri } webhook_url: type: [string, 'null'] description: Where this payment's webhooks go, when not your webhook URL. next_action: $ref: '#/components/schemas/NextAction' description: What your customer does next. `type` is `DISPLAY_QR`, `REDIRECT`, `PAY_AT_COUNTER`, or null once the payment is final. `qr_string`, `checkout_url` and `payment_code` are each null unless they apply. With `HOSTED` (the default), `type` is `REDIRECT` and `checkout_url` is Weav's payment page (the test checkout with a test key), for every channel. For QR Ph, `qr_ph_app` is the app you chose, and `instructions` lists the how-to-pay steps (`title`, `description`) when you asked for `DIRECT`. test_checkout_url: type: [string, 'null'] format: uri description: 'Test mode only: the test checkout page, where you pay, decline or let this payment expire, for every channel (a counter payment with `DIRECT` has no other way to finish). Anyone with the link can open it. Null in live mode.' failure: type: [object, 'null'] description: '`code` and `message` when the payment failed. Codes: `EXPIRED`, `DECLINED`, `PROVIDER_ERROR`.' properties: code: { type: string, enum: [EXPIRED, DECLINED, PROVIDER_ERROR], } message: { type: string } expires_at: type: string format: date-time description: When an unpaid payment fails (`failure.code` `EXPIRED`). completed_at: type: [string, 'null'] format: date-time description: When the customer paid, as the provider reports it. failed_at: type: [string, 'null'] format: date-time description: When the payment failed. cancelled_at: type: [string, 'null'] format: date-time description: When the payment was canceled. reversed_at: type: [string, 'null'] format: date-time description: When the payment was reversed. created_at: type: string format: date-time description: When Weav created the payment. updated_at: type: string format: date-time description: When the payment last changed. PaymentResponse: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: data: type: object properties: payment: { $ref: '#/components/schemas/Payment' } CheckoutStatus: type: string enum: [OPEN, COMPLETED, EXPIRED, CANCELLED] CheckoutItem: type: object required: [name, quantity, unit_amount] properties: name: { type: string, maxLength: 255, example: Canvas tote bag } quantity: { type: integer, minimum: 1, maximum: 9999, example: 1 } unit_amount: { type: number, description: 'Pesos, as a JSON number.', example: 1000.00, } amount: { type: number, readOnly: true, description: '`quantity` × `unit_amount`.', } CreateCheckout: type: object description: Send `items` or `amount`, never both. properties: items: type: [array, 'null'] minItems: 1 maxItems: 50 items: { $ref: '#/components/schemas/CheckoutItem' } description: An order, up to 50 items. Each has `name` (up to 255 characters), `quantity` (1 to 9,999) and `unit_amount` (pesos, a JSON number). Weav multiplies and adds them up; the total must be within your payment limits. amount: { type: [number, 'null'], description: 'Pesos. Within your payment limits.', example: 1250.00, } currency: { type: [string, 'null'], enum: [PHP, null] } description: type: [string, 'null'] maxLength: 255 description: What it's for, up to 255 characters. Your customer sees it. external_reference_id: { type: [string, 'null'], maxLength: 64, description: 'Unique across your checkouts in this mode when given.', } channels: { type: [array, 'null'], items: { $ref: '#/components/schemas/Channel' }, description: "Only these channels. Default every channel that's on.", } qr_ph_apps: type: [array, 'null'] description: QR Ph only as these bank or e-wallet apps, for example a UnionBank link. Needs QR Ph among the channels. items: type: string enum: [ BDO, CHINABANK, GOTYME, LANDBANK, METROBANK, PNB, RCBC, ROBINSONS_BANK, SECURITY_BANK, UNIONBANK, GRABPAY, SHOPEEPAY, ] save_payment_method: type: [boolean, 'null'] description: "If your customer pays by card, also saves the card for later charges (auto-debit). Send `customer.id`. They agree to future charges on Weav's payment page, and their bank's check for this payment also confirms the card. Another way to pay saves nothing: send `channels: [CARD]` to take cards only. The payment's `payment_method_id` is the saved card: you get `PAYMENT_COMPLETED`, then `PAYMENT_METHOD_SAVED`. If that payment isn't paid, the card isn't kept (`PAYMENT_METHOD_FAILED`). Off until Weav turns on saving cards for your account (422 `4220401`)." example: true customer: type: [object, 'null'] description: All optional. With a name, your customer isn't asked for one; with an email, they get a receipt. properties: id: { type: string, maxLength: 64, pattern: '^[A-Za-z0-9._:@-]+$', example: USER-123, description: 'With `save_payment_method` only, and required then: your own ID for this customer. Their saved cards are listed by it (`GET /v1/payment-methods?customer_id=`).', } name: { type: [string, 'null'], maxLength: 255 } email: { type: [string, 'null'], format: email } mobile_no: { type: [string, 'null'], example: '09171234567' } success_url: { type: [string, 'null'], format: uri } cancel_url: type: [string, 'null'] format: uri maxLength: 2048 description: HTTPS. Where your customer goes if they leave, or the checkout expires or is canceled. webhook_url: { type: [string, 'null'], format: uri } expires_in_minutes: type: [integer, 'null'] minimum: 5 maximum: 10080 default: 1440 description: How long it stays open, 5 to 10,080 (7 days). Default 1,440 (24 hours). Checkout: type: object properties: reference_id: { type: string, example: CK4T8M2Q7X9KBA } external_reference_id: { type: [string, 'null'] } type: { type: string, enum: [ORDER, AMOUNT] } status: { $ref: '#/components/schemas/CheckoutStatus' } currency: { $ref: '#/components/schemas/Currency' } amount: { type: number, description: 'The total, in pesos.' } description: { type: [string, 'null'] } items: { type: array, items: { $ref: '#/components/schemas/CheckoutItem' }, } channels: { type: [array, 'null'], items: { $ref: '#/components/schemas/Channel' }, } qr_ph_apps: { type: [array, 'null'], items: { type: string } } customer: type: object properties: id: { type: [string, 'null'], description: 'Your ID for the customer, with `save_payment_method`.', } name: { type: [string, 'null'] } email: { type: [string, 'null'] } mobile_no: { type: [string, 'null'] } save_payment_method: { type: boolean, description: "A card payment also saves the card (the payment's `payment_method_id`).", } checkout_url: { type: string, format: uri, example: 'https://pay.weavpayments.com/checkout/CK4T8M2Q7X9KBA', } success_url: { type: [string, 'null'] } cancel_url: { type: [string, 'null'] } webhook_url: { type: [string, 'null'] } payment: { oneOf: [ { $ref: '#/components/schemas/Payment' }, { type: 'null' }, ], description: 'The payment that paid it.', } expires_at: { type: string, format: date-time } completed_at: { type: [string, 'null'], format: date-time } expired_at: { type: [string, 'null'], format: date-time } cancelled_at: { type: [string, 'null'], format: date-time } created_at: { type: string, format: date-time } updated_at: { type: string, format: date-time } CheckoutResponse: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: data: type: object properties: checkout: { $ref: '#/components/schemas/Checkout' } PaymentMethodStatus: type: string enum: [PENDING, ACTIVE, FAILED, REMOVED] description: '`PENDING` until your customer saves it and their bank confirms it; `ACTIVE` (chargeable); `FAILED` when that never happens; `REMOVED`.' CreatePaymentMethod: type: object required: [type, customer] properties: type: { type: string, enum: [CARD] } customer: type: object required: [id] properties: id: type: string maxLength: 64 pattern: '^[A-Za-z0-9._:@-]+$' description: Your own ID for the customer. List their saved methods with it. example: USER-123 name: { type: [string, 'null'], maxLength: 255, description: "Weav's save page asks your customer when you leave it out.", } email: { type: [string, 'null'], format: email, maxLength: 255, } success_url: { type: [string, 'null'], format: uri, maxLength: 2048, description: "HTTPS. Where your customer goes once it's saved.", } cancel_url: { type: [string, 'null'], format: uri, maxLength: 2048, description: "HTTPS. Where your customer goes if they leave, or the bank's check fails.", } webhook_url: { type: [string, 'null'], maxLength: 2048, description: "This payment method's webhooks go here instead of your webhook URL.", } PaymentMethod: type: object properties: id: { type: string, example: PM8K2Q7X9KBAT4MZ3N } type: { type: string, enum: [CARD] } status: { $ref: '#/components/schemas/PaymentMethodStatus' } customer: type: object properties: id: { type: string } name: { type: [string, 'null'] } email: { type: [string, 'null'] } card: type: [object, 'null'] description: Once saved. Never the card number. properties: brand: { type: string, enum: [VISA, MASTERCARD, JCB], description: 'From the card processor.', } last4: { type: string, example: '1381' } exp_month: { type: [integer, 'null'], minimum: 1, maximum: 12, example: 12, description: 'The expiry month your customer typed. Ask them for a new card before it passes (`expires_by` on the list).', } exp_year: { type: [integer, 'null'], example: 2030, description: 'Four digits.', } label: { type: [string, 'null'], example: 'Visa •••• 1381', description: 'To show your customer.', } next_action: type: object properties: type: { type: [string, 'null'], enum: [REDIRECT, null] } checkout_url: { type: [string, 'null'], format: uri, description: "Weav's save page, while `PENDING`.", } success_url: { type: [string, 'null'], format: uri } cancel_url: { type: [string, 'null'], format: uri } webhook_url: { type: [string, 'null'] } expires_at: { type: [string, 'null'], format: date-time, description: 'When the save link ends, while `PENDING`.', } activated_at: { type: [string, 'null'], format: date-time } failed_at: { type: [string, 'null'], format: date-time } removed_at: { type: [string, 'null'], format: date-time } created_at: { type: string, format: date-time } updated_at: { type: string, format: date-time } PaymentMethodResponse: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: data: type: object properties: payment_method: { $ref: '#/components/schemas/PaymentMethod' } Balance: type: object properties: currency: { $ref: '#/components/schemas/Currency' } available: { type: number, description: 'What you can withdraw.' } on_hold: { type: number, description: Withdrawals on their way to your bank., } as_of: { type: [string, 'null'], format: date-time, description: Time of the latest ledger entry., } LedgerEntry: type: object properties: reference_id: { type: string, example: LE3M8Q2W6K9TZA } type: $ref: '#/components/schemas/LedgerEntryType' description: '`PAYMENT`, `REFUND`, `REVERSAL`, `WITHDRAWAL`, `WITHDRAWAL_RETURNED`, `FEE` or `ADJUSTMENT`.' currency: { $ref: '#/components/schemas/Currency' } amount: { type: number, description: 'Signed.' } balance_after: type: number description: Your balance after this entry. source: type: [object, 'null'] description: '`type` (`PAYMENT`, `REFUND`, `REVERSAL` or `WITHDRAWAL`) and `reference_id` of what caused it. Null when nothing did, such as an adjustment.' properties: type: { type: string, enum: [PAYMENT, WITHDRAWAL, REFUND, REVERSAL], } reference_id: { type: string } description: type: [string, 'null'] description: A readable label, mainly for adjustments. posted_at: type: string format: date-time description: When the entry took effect. LedgerEntryType: type: string enum: [ PAYMENT, REFUND, REVERSAL, WITHDRAWAL, WITHDRAWAL_RETURNED, FEE, ADJUSTMENT, ] Withdrawal: type: object properties: reference_id: { type: string, example: WD8H2K4M6P9QRT } currency: { $ref: '#/components/schemas/Currency' } amount: { type: number } fee: { type: [number, 'null'] } total: type: [number, 'null'] description: '`amount` plus `fee`.' status: type: string enum: [PENDING, FOR_SETTLEMENT, COMPLETED, FAILED] description: '`PENDING`, `FOR_SETTLEMENT`, `COMPLETED` or `FAILED`.' rail: type: [string, 'null'] enum: [INSTAPAY, PESONET, null] description: INSTAPAY (real time) for 50,000.00 or less; PESONET (batch, not real time) above that, or when the bank isn't on InstaPay. Null for withdrawals made before rails were recorded. provider_reference_id: type: [string, 'null'] description: The bank partner's transfer reference. Null until known. channel_reference_id: type: [string, 'null'] description: The InstaPay or PESONet reference. Null until known. destination: type: object description: '`bank_name`, `account_name`, `account_number_last4`. Never the full account number.' properties: bank_name: { type: string } account_name: { type: string } account_number_last4: { type: string, example: '5678' } failure: type: [object, 'null'] description: '`code` and `message` when the withdrawal failed. `code` can be null.' properties: code: { type: [string, 'null'] } message: { type: string } requested_at: { type: string, format: date-time } completed_at: { type: [string, 'null'], format: date-time } failed_at: { type: [string, 'null'], format: date-time } updated_at: { type: string, format: date-time } ChannelStatus: type: object properties: channel: $ref: '#/components/schemas/Channel' description: The value you send when creating a payment. name: { type: string, example: GCash } is_enabled: type: boolean description: Whether new payments can use it (allowed by Weav and switched on by you). apps: type: array description: QR Ph only. The bank and e-wallet apps you can send as `qr_ph_app`. Empty for other channels. items: type: object properties: code: { type: string, example: BDO } name: { type: string, example: BDO Pay } maintenance: type: [object, 'null'] description: Always null for now. Scheduled maintenance windows aren't shown here yet. WebhookEventName: type: string enum: [ PAYMENT_COMPLETED, PAYMENT_FAILED, PAYMENT_CANCELLED, PAYMENT_REVERSED, PAYMENT_REFUNDED, CHECKOUT_COMPLETED, CHECKOUT_EXPIRED, PAYMENT_METHOD_SAVED, PAYMENT_METHOD_FAILED, PAYMENT_METHOD_REMOVED, WITHDRAWAL_COMPLETED, WITHDRAWAL_FAILED, ] WebhookPayload: type: object required: [event, sent_at, data] properties: event: { $ref: '#/components/schemas/WebhookEventName' } sent_at: { type: string, format: date-time, description: Fresh on every attempt., } data: type: object description: '`payment` (a Payment) for PAYMENT_* events; `checkout` (a Checkout) for CHECKOUT_* events; `withdrawal` (a Withdrawal) for WITHDRAWAL_* events.' properties: payment: { $ref: '#/components/schemas/Payment' } checkout: { $ref: '#/components/schemas/Checkout' } withdrawal: { $ref: '#/components/schemas/Withdrawal' }