{ "openapi": "3.0.3", "info": { "title": "Jual Pulsa Aja Merchant Payment API", "description": "Payment gateway abstraction over LinkQu. Create QRIS, one-time and dedicated Virtual Accounts, bank transfers and e-wallet top-ups with a single REST API. Webhooks notify your application when a transaction reaches a final state.\n\n## Authentication\nSend `Authorization: Bearer client_id:client_secret` on every request. Both values come from the merchant dashboard under API Integration.\n\n## Idempotency\nFor mutating requests (create/confirm), optionally send `X-Idempotency-Key: ` — repeated requests with the same key return the first response instead of creating duplicates.\n\n## Webhooks\nRegister a callback URL on your API client. We POST JSON with an `event` field: `transaction.paid`, `transaction.failed`, `transaction.expired`, `transaction.cancelled`. The `X-Webhook-Signature` header is an HMAC-SHA256 of the raw body using your client secret. Transient delivery failures are retried automatically with exponential backoff.", "version": "1.0.0", "contact": { "email": "support@jualpulsaaja.com" } }, "servers": [ { "url": "https://merchant.jualpulsaaja.com/api/v1", "description": "Production" } ], "tags": [ { "name": "QRIS", "description": "Receive payments via QRIS (customer scans and pays)" }, { "name": "Virtual Account", "description": "One-time VA per payment, or dedicated VA per merchant+bank" }, { "name": "Bank Transfer", "description": "Outbound transfer to an Indonesian bank account (two-step: inquiry + confirm)" }, { "name": "E-Wallet", "description": "Outbound top-up to DANA/OVO/GoPay/ShopeePay/LinkAja (two-step: inquiry + confirm)" }, { "name": "Transactions", "description": "Query transaction state and event history" }, { "name": "Devices", "description": "Push-notification device registration" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Format: Bearer client_id:client_secret" } }, "headers": { "XIdempotencyKey": { "description": "Optional unique key to make the request idempotent (replay returns the first response).", "schema": { "type": "string" } } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "description": "Machine-readable error code (validation_failed, upstream_error, insufficient_balance, kyc_required, not_found, ...)" }, "message": { "type": "string", "description": "Human-readable description" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field-level validation errors (422 only)" }, "upstream_status": { "type": "integer", "description": "LinkQu HTTP status when error=upstream_error" } }, "required": [ "ok", "error" ] }, "Fees": { "type": "object", "properties": { "linkqu_fee": { "type": "integer", "description": "Fee charged by LinkQu (IDR)" }, "platform_fee": { "type": "integer", "description": "Platform markup (IDR)" }, "total_fee": { "type": "integer", "description": "linkqu_fee + platform_fee (IDR)" }, "net_amount": { "type": "integer", "description": "amount - total_fee credited to merchant balance (IDR)" } } }, "QrisTransaction": { "type": "object", "properties": { "id": { "type": "integer" }, "partner_reff": { "type": "string", "description": "Unique reference; use for status checks and webhook correlation" }, "amount": { "type": "integer" }, "status": { "type": "string", "enum": [ "created", "waiting_payment", "paid", "expired", "failed", "cancelled" ] }, "expires_at": { "type": "string", "format": "date-time" } } }, "QrisPayload": { "type": "object", "properties": { "qr_image_url": { "type": "string", "format": "uri", "description": "QR code image to display to the customer" }, "qr_string": { "type": "string", "description": "Raw QRIS payload string" }, "qris_id": { "type": "string" } } }, "QrisCreateRequest": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "integer", "minimum": 10000, "description": "Amount in IDR" }, "customer_name": { "type": "string", "maxLength": 100 }, "customer_email": { "type": "string", "format": "email", "maxLength": 200 }, "customer_phone": { "type": "string", "maxLength": 50 }, "description": { "type": "string", "maxLength": 200 } } }, "VaCreateRequest": { "type": "object", "required": [ "amount", "bank_code" ], "properties": { "amount": { "type": "integer", "minimum": 10000, "maximum": 2000000000 }, "bank_code": { "type": "string", "maxLength": 10, "description": "e.g. 002 (BRI), 022 (CIMB Niaga), 013 (Permata). Fetch the current list from GET /payments/va/banks" }, "customer_name": { "type": "string", "maxLength": 100 }, "customer_email": { "type": "string", "format": "email", "maxLength": 200 }, "customer_phone": { "type": "string", "maxLength": 50 }, "expires_in_hours": { "type": "integer", "minimum": 1, "maximum": 720, "default": 24, "description": "VA lifetime in hours (max 30 days)" }, "description": { "type": "string", "maxLength": 200 } } }, "VaPayment": { "type": "object", "properties": { "partner_reff": { "type": "string" }, "amount": { "type": "integer" }, "status": { "type": "string" }, "bank_code": { "type": "string" }, "bank_name": { "type": "string" }, "virtual_account_number": { "type": "string" }, "account_name": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "paid_at": { "type": "string", "format": "date-time", "nullable": true }, "failed_at": { "type": "string", "format": "date-time", "nullable": true } } }, "DedicatedVa": { "type": "object", "properties": { "id": { "type": "integer" }, "bank_code": { "type": "string" }, "bank_name": { "type": "string" }, "virtual_account_number": { "type": "string" }, "account_name": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "TransferInquiryRequest": { "type": "object", "required": [ "amount", "bank_code", "account_number" ], "properties": { "amount": { "type": "integer", "minimum": 10000, "maximum": 50000000 }, "bank_code": { "type": "string", "maxLength": 10 }, "account_number": { "type": "string", "minLength": 4, "maxLength": 64 } } }, "ConfirmRequest": { "type": "object", "required": [ "partner_reff", "pin" ], "properties": { "partner_reff": { "type": "string" }, "pin": { "type": "string", "pattern": "^[0-9]{6}$", "description": "6-digit transaction PIN set in the merchant profile" } } }, "EwalletInquiryRequest": { "type": "object", "required": [ "amount", "product_code", "phone_number" ], "properties": { "amount": { "type": "integer", "minimum": 10000, "maximum": 5000000 }, "product_code": { "type": "string", "maxLength": 32, "description": "e.g. DANA, OVO, GOPAY, SHOPEEPAY, LINKAJA. Fetch from GET /ewallet/products" }, "phone_number": { "type": "string", "pattern": "^(?:\\+62|62|0)?8[0-9]{8,11}$", "description": "Customer phone (Indonesian mobile format)" } } }, "DeviceRegisterRequest": { "type": "object", "required": [ "token", "platform" ], "properties": { "token": { "type": "string", "maxLength": 255, "description": "FCM push token" }, "platform": { "type": "string", "enum": [ "android", "ios", "web" ] }, "app_version": { "type": "string", "maxLength": 32 }, "device_name": { "type": "string", "maxLength": 128 } } }, "TransactionListItem": { "type": "object", "properties": { "partner_reff": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "integer" }, "net_amount": { "type": "integer" }, "total_fee": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } }, "TransactionDetail": { "type": "object", "properties": { "partner_reff": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "integer" }, "paid_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "fees": { "$ref": "#/components/schemas/Fees" }, "events": { "type": "array", "items": { "type": "object", "properties": { "event_type": { "type": "string" }, "from": { "type": "string", "nullable": true }, "to": { "type": "string" }, "source": { "type": "string" }, "description": { "type": "string", "nullable": true }, "at": { "type": "string", "format": "date-time" } } } } } }, "WebhookPayload": { "type": "object", "description": "POSTed to your callback_url when a transaction reaches a final state. Verify X-Webhook-Signature = HMAC-SHA256(raw body, client_secret).", "properties": { "event": { "type": "string", "enum": [ "transaction.paid", "transaction.failed", "transaction.expired", "transaction.cancelled" ] }, "partner_reff": { "type": "string" }, "transaction": { "type": "object", "properties": { "partner_reff": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "integer" }, "fees": { "$ref": "#/components/schemas/Fees" }, "bank_code": { "type": "string", "nullable": true }, "bank_name": { "type": "string", "nullable": true }, "account_number": { "type": "string", "nullable": true }, "account_name": { "type": "string", "nullable": true }, "product_code": { "type": "string", "nullable": true }, "payment_method": { "type": "string", "nullable": true }, "paid_at": { "type": "string", "format": "date-time", "nullable": true }, "failed_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "required": [ "event", "partner_reff", "transaction" ] } }, "responses": { "ValidationError": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "KycRequired": { "description": "KYC verification required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "UpstreamError": { "description": "LinkQu upstream error (bad gateway)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "paths": { "/qris": { "post": { "tags": [ "QRIS" ], "summary": "Create a QRIS payment", "description": "Creates a new QRIS transaction. Display the returned QR image to the customer; the transaction flips to paid via callback and your balance is credited (QRIS funds settle H+1).", "operationId": "createQris", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrisCreateRequest" } } } }, "responses": { "201": { "description": "QRIS created", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "transaction": { "$ref": "#/components/schemas/QrisTransaction" }, "fees": { "$ref": "#/components/schemas/Fees" }, "qris": { "$ref": "#/components/schemas/QrisPayload" } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/transactions": { "get": { "tags": [ "Transactions" ], "summary": "List recent transactions", "operationId": "listTransactions", "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated transaction list", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionListItem" } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "total": { "type": "integer" } } } } } } } } } } }, "/transactions/{partner_reff}": { "get": { "tags": [ "Transactions" ], "summary": "Get transaction detail with event history", "operationId": "getTransaction", "parameters": [ { "name": "partner_reff", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "transaction": { "$ref": "#/components/schemas/TransactionDetail" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/payments/va": { "post": { "tags": [ "Virtual Account" ], "summary": "Create a one-time Virtual Account payment", "description": "Creates a brand-new VA for a specific amount. The customer transfers the exact amount before expiry. Each call produces a new VA; it cannot be reused once paid or expired.", "operationId": "createOneTimeVa", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaCreateRequest" } } } }, "responses": { "201": { "description": "VA created", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "payment": { "$ref": "#/components/schemas/VaPayment" }, "fees": { "$ref": "#/components/schemas/Fees" } } } } } }, "403": { "$ref": "#/components/responses/KycRequired" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/payments/va/banks": { "get": { "tags": [ "Virtual Account" ], "summary": "List banks supported for one-time VA", "operationId": "listVaBanks", "responses": { "200": { "description": "Supported banks", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "banks": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } } } } } } } } } } }, "/payments/va/{partner_reff}": { "get": { "tags": [ "Virtual Account" ], "summary": "Get one-time VA payment status", "description": "Poll this endpoint until status is 'paid' (success) or 'expired'/'failed' (no money came in).", "operationId": "getOneTimeVa", "parameters": [ { "name": "partner_reff", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "VA payment state", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "payment": { "$ref": "#/components/schemas/VaPayment" }, "fees": { "$ref": "#/components/schemas/Fees" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/virtual-accounts": { "post": { "tags": [ "Virtual Account" ], "summary": "Create or get a dedicated Virtual Account", "description": "Dedicated VA for this merchant+bank (currently BRI 002 and Permata 013). If an active VA already exists for the bank, it is returned instead of creating a new one.", "operationId": "createDedicatedVa", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "bank_code" ], "properties": { "bank_code": { "type": "string", "maxLength": 10 } } } } } }, "responses": { "200": { "description": "Existing VA returned" }, "201": { "description": "New VA created" }, "403": { "$ref": "#/components/responses/KycRequired" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/UpstreamError" } } }, "get": { "tags": [ "Virtual Account" ], "summary": "List active dedicated Virtual Accounts", "operationId": "listDedicatedVas", "responses": { "200": { "description": "Active VAs", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DedicatedVa" } } } } } } } } } }, "/virtual-accounts/{id}": { "get": { "tags": [ "Virtual Account" ], "summary": "Get dedicated VA detail", "operationId": "getDedicatedVa", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "VA detail" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/transfer/inquiry": { "post": { "tags": [ "Bank Transfer" ], "summary": "Step 1: bank transfer inquiry", "description": "Verifies the destination account (returns account name) and calculates fees. No money moves on inquiry. Follow with POST /transfer/confirm.", "operationId": "transferInquiry", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferInquiryRequest" } } } }, "responses": { "200": { "description": "Inquiry result with fees", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "transaction": { "type": "object", "properties": { "id": { "type": "integer" }, "partner_reff": { "type": "string" }, "amount": { "type": "integer" }, "status": { "type": "string" }, "bank_code": { "type": "string" }, "bank_name": { "type": "string" }, "account_number": { "type": "string" }, "account_name": { "type": "string" } } }, "fees": { "allOf": [ { "$ref": "#/components/schemas/Fees" }, { "type": "object", "properties": { "total_debit": { "type": "integer", "description": "amount + total_fee debited from balance on confirm" } } } ] } } } } } }, "403": { "$ref": "#/components/responses/KycRequired" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/transfer/confirm": { "post": { "tags": [ "Bank Transfer" ], "summary": "Step 2: confirm bank transfer", "description": "Confirms the transfer with the 6-digit transaction PIN. Funds are debited first; on gateway failure they are refunded automatically. Final state arrives via webhook when the transfer is pending.", "operationId": "transferConfirm", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmRequest" } } } }, "responses": { "200": { "description": "Transfer confirmed (status may be paid or pending)", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "transaction": { "type": "object", "properties": { "partner_reff": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "integer" } } }, "message": { "type": "string", "nullable": true } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/transfer/banks": { "get": { "tags": [ "Bank Transfer" ], "summary": "List banks supported for outbound transfer", "operationId": "listTransferBanks", "responses": { "200": { "description": "Bank list", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } } } } } } } } } } }, "/ewallet/inquiry": { "post": { "tags": [ "E-Wallet" ], "summary": "Step 1: e-wallet top-up inquiry", "operationId": "ewalletInquiry", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EwalletInquiryRequest" } } } }, "responses": { "200": { "description": "Inquiry result with fees" }, "403": { "$ref": "#/components/responses/KycRequired" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/ewallet/confirm": { "post": { "tags": [ "E-Wallet" ], "summary": "Step 2: confirm e-wallet top-up", "operationId": "ewalletConfirm", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmRequest" } } } }, "responses": { "200": { "description": "Top-up confirmed (status may be paid or pending)" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/ewallet/products": { "get": { "tags": [ "E-Wallet" ], "summary": "List available e-wallet products", "operationId": "listEwalletProducts", "responses": { "200": { "description": "Product list", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" } } } } } } } } } } } }, "/devices": { "post": { "tags": [ "Devices" ], "summary": "Register a push-notification device", "description": "Registers or refreshes a device token for push notifications. Repeating the same token just bumps last_seen_at.", "operationId": "registerDevice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceRegisterRequest" } } } }, "responses": { "200": { "description": "Device registered" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/devices/{token}": { "delete": { "tags": [ "Devices" ], "summary": "Disable a device (e.g. on logout)", "operationId": "unregisterDevice", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Device disabled" } } } } } }