{ "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.\n\n- **Base URL:** `https://api.weavpayments.com` (paths start with `/v1`).\n- **Auth:** send your API key as a Bearer token. `wv_test_` keys use test mode, `wv_live_` keys use live mode.\n- **Money:** JSON numbers in the currency's major unit (e.g. `1250.00` PHP). Never strings.\n- **Times:** ISO 8601 with offset, Asia/Manila (`+08:00`).\n- **Envelope:** every response is `{ code, success, message, data }`; errors add `errors` for field problems.\n- **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.\n- **Pagination:** cursor based (`cursor`, `per_page` up to 100). There's no total count; stop when `is_last_page` is true.\n\nThis is a draft for review. Response codes and some endpoints are proposed and may change before general availability.\n", "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.\n\nEach 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.\n", "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.\n\nWith 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.\n", "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.\n\nYou 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`).\n\nSaving 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.\n", "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.\nEach 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).\nThe 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`).\n", "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.\n\n**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.\n\n**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.\n", "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" } } } } } } } }