{"openapi":"3.0.0","paths":{"/v1/payments":{"post":{"description":"Creates a payment intent and initiates it with the provider routed for the chosen method.\n\nRequires BOTH an `Idempotency-Key` header and a valid `X-Paygate-Signature`. The response contains a `nextAction` the customer must complete: a redirect URL for GCash/Maya/card, or a QR payload for QR Ph.","operationId":"PaymentsController_create","parameters":[{"name":"X-Paygate-Signature","in":"header","description":"t=<unix>,v1=<hex HMAC-SHA256 of \"<t>.<idempotency key>.<raw body>\">","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"Unique UUID per logical operation. Reuse it verbatim when retrying.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentDto"}}}},"responses":{"201":{"description":"Payment intent created"},"409":{"description":"Idempotency key reused with a different body, or duplicate merchantOrderId"},"503":{"description":"No provider is currently available for this method"}},"security":[{"ApiKey":[]}],"summary":"Create a payment","tags":["Payments"]},"get":{"description":"Cursor-paginated, newest first.","operationId":"PaymentsController_list","parameters":[{"name":"status","required":true,"in":"query","schema":{"type":"string"}},{"name":"cursor","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"ApiKey":[]}],"summary":"List payments","tags":["Payments"]}},"/v1/payments/{reference}":{"get":{"operationId":"PaymentsController_retrieve","parameters":[{"name":"reference","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"404":{"description":"No such payment belongs to this merchant"}},"security":[{"ApiKey":[]}],"summary":"Retrieve a payment","tags":["Payments"]}},"/v1/payments/{reference}/capture":{"post":{"description":"Only valid while the payment is REQUIRES_CAPTURE (captureMode=MANUAL).","operationId":"PaymentsController_capture","parameters":[{"name":"reference","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"ApiKey":[]}],"summary":"Capture an authorised payment","tags":["Payments"]}},"/v1/payments/{reference}/cancel":{"post":{"operationId":"PaymentsController_cancel","parameters":[{"name":"reference","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"ApiKey":[]}],"summary":"Cancel a payment that has not reached a terminal state","tags":["Payments"]}},"/v1/payments/{reference}/refunds":{"post":{"description":"Full or partial. Omit `amount` to refund the entire remaining balance. Not every rail supports online refunds.","operationId":"PaymentsController_refund","parameters":[{"name":"reference","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRefundDto"}}}},"responses":{"422":{"description":"Payment not refundable, or amount exceeds the refundable balance"}},"security":[{"ApiKey":[]}],"summary":"Refund a payment","tags":["Payments"]}},"/v1/payment-methods":{"get":{"description":"Reflects live provider health and configuration. Render your checkout from this, not a hardcoded list.","operationId":"PaymentMethodsController_list","parameters":[],"responses":{"200":{"description":""}},"security":[{"ApiKey":[]}],"summary":"List currently available payment methods","tags":["Payments"]}},"/v1/webhook-endpoints":{"post":{"description":"Returns the signing secret ONCE. Store it immediately — it is encrypted at rest and never shown again. Use it to verify the X-Paygate-Signature header on every delivery.","operationId":"WebhookEndpointsController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEndpointDto"}}}},"responses":{"201":{"description":""}},"security":[{"ApiKey":[]}],"summary":"Register a webhook endpoint","tags":["Webhooks"]},"get":{"operationId":"WebhookEndpointsController_list","parameters":[],"responses":{"200":{"description":""}},"security":[{"ApiKey":[]}],"summary":"List webhook endpoints","tags":["Webhooks"]}},"/v1/webhook-endpoints/{id}":{"delete":{"operationId":"WebhookEndpointsController_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"ApiKey":[]}],"summary":"Delete a webhook endpoint","tags":["Webhooks"]}},"/v1/merchant":{"get":{"operationId":"MerchantsController_me","parameters":[],"responses":{"200":{"description":""}},"security":[{"ApiKey":[]}],"summary":"Retrieve the authenticated merchant","tags":["Merchant"]}},"/v1/merchant/api-keys":{"get":{"description":"Secrets are never returned — only prefixes and usage metadata.","operationId":"MerchantsController_listKeys","parameters":[],"responses":{"200":{"description":""}},"security":[{"ApiKey":[]}],"summary":"List API keys","tags":["Merchant"]}},"/v1/merchant/api-keys/{prefix}":{"delete":{"operationId":"MerchantsController_revoke","parameters":[{"name":"prefix","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"ApiKey":[]}],"summary":"Revoke an API key immediately","tags":["Merchant"]}},"/v1/applications":{"post":{"description":"Public: a prospective merchant applies to use Paygate. Returns a reference they can quote when following up. Contact details are encrypted at rest.","operationId":"ApplicationsController_submit","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationDto"}}}},"responses":{"201":{"description":"Application received"}},"summary":"Submit an onboarding application","tags":["Onboarding"]}}},"info":{"title":"Paygate API","description":"Payment gateway for the Philippine market — GCash, Maya, QR Ph, cards and BancNet direct debit.\n\n## Authentication\nSend your secret key as a bearer token:\n\n```\nAuthorization: Bearer sk_live_<prefix>_<secret>\n```\n\n## Request signing\nMoney-moving endpoints additionally require an HMAC signature over the raw body:\n\n```\nX-Paygate-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<idempotency key>.<raw body>\">\n```\n\nSignatures older than 5 minutes are rejected. Binding the idempotency key into the signature means a captured request replayed verbatim returns the stored response instead of charging again, while swapping the key invalidates the signature.\n\n## Idempotency\nEvery POST that moves money requires an `Idempotency-Key`. Retrying with the same key returns the original response instead of charging twice.\n\n## Amounts\nAll amounts are integers in **minor units** (centavos). PHP 1,500.00 is `150000`.","version":"1.0.0","contact":{}},"tags":[],"servers":[{"url":"https://paygate.cdotechdev.biz"}],"components":{"securitySchemes":{"ApiKey":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Your secret API key"}},"schemas":{"RedirectUrlsDto":{"type":"object","properties":{"success":{"type":"string","example":"https://shop.example.com/checkout/success"},"failure":{"type":"string","example":"https://shop.example.com/checkout/failed"},"cancel":{"type":"string","example":"https://shop.example.com/cart"}},"required":["success","failure","cancel"]},"CustomerDto":{"type":"object","properties":{"name":{"type":"string","example":"Juan Dela Cruz"},"email":{"type":"string","example":"juan@example.com"},"phone":{"type":"string","example":"+639171234567","description":"E.164 format"}}},"CreatePaymentDto":{"type":"object","properties":{"amount":{"type":"number","example":150000,"description":"Amount in MINOR UNITS (centavos). PHP 1,500.00 is 150000. Must be a positive integer — decimals are rejected."},"currency":{"type":"string","example":"PHP","default":"PHP"},"method":{"type":"string","enum":["GCASH","MAYA_WALLET","QRPH","CARD","BANCNET_DEBIT"],"example":"GCASH"},"captureMode":{"type":"string","enum":["AUTOMATIC","MANUAL"],"default":"AUTOMATIC","description":"MANUAL authorises funds now and captures later. Not every rail supports it."},"description":{"type":"string","example":"Order #10234 — 2 items"},"merchantOrderId":{"type":"string","example":"ORD-10234","description":"Your own order id. Unique per merchant — a second intent with the same value is rejected, which stops double-charging on a double-submit."},"redirectUrls":{"$ref":"#/components/schemas/RedirectUrlsDto"},"customer":{"$ref":"#/components/schemas/CustomerDto"},"metadata":{"type":"object","example":{"cartId":"c_991","channel":"web"}}},"required":["amount","currency","method","redirectUrls"]},"CreateRefundDto":{"type":"object","properties":{"amount":{"type":"number","example":50000,"description":"Minor units. Omit to refund the full remaining capturable amount."},"reason":{"type":"string","example":"Customer returned the item"},"metadata":{"type":"object"}}},"CreateEndpointDto":{"type":"object","properties":{"url":{"type":"string","example":"https://shop.example.com/paygate/webhooks"},"enabledEvents":{"example":["payment.succeeded","payment.failed","refund.succeeded"],"description":"Empty array means \"send me everything\".","type":"array","items":{"type":"string"}}},"required":["url"]},"ApplicationDto":{"type":"object","properties":{"businessName":{"type":"string","example":"Acme Corp"},"businessType":{"type":"string","enum":["SOLE_PROPRIETORSHIP","PARTNERSHIP","CORPORATION","OPC","COOPERATIVE"]},"registrationNo":{"type":"string","example":"SEC 2026-123456","description":"SEC/DTI registration number"},"website":{"type":"string","example":"https://acme.ph"},"monthlyVolume":{"type":"string","enum":["UNDER_100K","FROM_100K_TO_1M","FROM_1M_TO_10M","OVER_10M"]},"contactName":{"type":"string","example":"Juan Dela Cruz"},"contactEmail":{"type":"string","example":"juan@acme.ph"},"contactPhone":{"type":"string","example":"+639171234567"},"useCase":{"type":"string","example":"Online checkout for our e-commerce store"},"requestedMethods":{"type":"array","example":["GCASH","QRPH"],"items":{"type":"string","enum":["GCASH","MAYA_WALLET","QRPH","CARD","BANCNET_DEBIT"]}}},"required":["businessName","businessType","monthlyVolume","contactName","contactEmail","contactPhone","useCase","requestedMethods"]}}}}