API Direct Connection

Local Acquirer

API Direct Connection

In API direct connection mode, the user selects a payment method in your website or app, and your server calls the interface corresponding to the payment method to create the payment. Interface returns uniform payment data payData, return the QR code content, jump link or virtual account according to different channels, and the merchant will render or display it accordingly.

1

Introduction to Modes

In pure API mode, Merchants are responsible for rendering payment pages. Compared to the cashier mode, the core differences are:

• The interface defines a fixed payment method: In the ordering interface, the merchant needs to specify a unique channel type and channel code (such as QR +PH_QRPH_DYNAMIC).
• Return to specific payment data: PayCools returns unified payData-- The QR channel returns the QR code content, the e-wallet returns the redirect link, and the VA/bill returns the virtual account or payment reference number; the merchant renders or redirects accordingly.
• Merchants implement their own checkout desk: Merchants need to develop their own checkout page, payment results page, and handle user interaction.

2

Applicable scenarios

• Fully customized experience required: I want to have complete control over the checkout page style and interaction process, and do not use the PayCools general checkout counter.
• Existing mature cashier system: Merchants already have a full-fledged checkout page, just connect to PayCools for payment information.
• Unified multi-channel payment required: Connect multiple payment channels at the same time, and want to display them uniformly on your own checkout page, rather than jumping to different third-party pages.

3

Interaction flow

The API direct connection mode does not display the PayCools payment method selection page. The payment page or payment guide that the user subsequently sees from the selected payment method and the returned payData Type decision.

4

Access Steps

1. Create a payment

After the user selects a payment method, create a payment by calling the payout interface on your server side. The following is an example of a request and response from the payout interface. View Document Interface

Create Payment Request Example

curl --location --request POST 'https://globalapi-dev.paycools.com:8902/open-api/payment/generate' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appId": "your appId",
    "sign": "********************************",
    "param": "{\"timestamp\":1790668386,\"mchOrderId\":\"xAlQ4NHqV183OAICTkp\",\"currency\":\"PHP\",\"countryCode\":\"PH\",\"channelType\":\"QR\",\"channelCode\":\"PH_QRPH_DYNAMIC\",\"customerName\":\"PayCools\",\"email\":\"test@email.com\",\"mobile\":\"09123456789\",\"amount\":10000,\"remark\":\"remark\",\"notifyUrl\":\"https://www.test.com\",\"redirectUrl\":\"https://www.test.com\",\"terminalType\":\"WEB\"}"
}'

Example of creating a payment response

{
  "code": 10000,
  "message": "Success",
  "data": {
    "mchOrderId": "huB7yF1l340",
    "transactionId": "CU5U4841812291227648",
    "transactionStatus": "PENDING",
    "payData": "00020101021128760011ph.ppmi.p2m0111OPDVPHM1XXX03157771480000000170416529481372394713405030005204601653036085802PH5908PayCools6015City Of Mandalu62310010ph.allbank05062110000803***88310012ph.ppmi.qrph0111OPDVPHM1XXXO6127DN0",
    "cashierUrl": "https://globalapi-dev.paycools.com:8904/webpay/cashier/9kbU8AGr0yWjMWTHxV-NbQ==",
    "channelType": "QR",
    "channelCode": "PH_QRPH_DYNAMIC"
  }
}

2. Direct the user to complete the payment

Upon successful creation of the payment, return the payData The type guides the user: QR content is rendered into a QR code for the user to scan; the jump URL is used for button jumping or direct jumping; the VA/reference number is displayed to the user to complete the transfer or payment.

3. Confirm Payment Result

Once the user has completed the payment, you can confirm the status of the payment by:

• Receive payment result notifications: API direct pairing transactions Payment result callbacks are sent for both successes and failures. When you receive the notification, please follow the corresponding notification document to complete the verification and update the order status. The delivery and retry rules for callbacks (success judged by HTTP 200, retry frequency and time limit, etc.) are shown in Payment General Rules · Callback Notification Rules.
• Proactively query payment results: If you do not receive a notification or need to reconfirm the payment status, you can check the corresponding payment record.

Please refer to the status obtained by payment result notification or proactive inquiry. The user's return to your page does not mean that the payment has been successful. You can check the final status of the order in the background or through the query interface.

5

Interface description

The pure API mode calls the collection interface to create a payment, and the key parameters for placing an order are described as follows:

Parameter	Description
mchOrderId	Merchant Order Number (Unique)
countryCode	Transaction country, e.g. PH
currency	Currency, must correspond to the transaction country, such as PHP
channelType	Channel type, such as QR/EWALLET/VA, etc.
channelCode	Channel code, must correspond to channelType, such as PH_QRPH_dynamic
customerName	Payer Name
email	Payer email
mobile	Payer phone number
amount	Order Amount
notifyUrl	Payment Result Asynchronous Notification Address
redirectUrl	User returns to the merchant's address after payment is complete

note

PayCools does not verify the authenticity of the payer's name, email address, phone number, or other personal information (it does not verify whether the number is real or registered), but it does verify the format. Refer to Payment Rules for the correct format for the relevant country.

Refer to API Documentation for complete API parameter descriptions, signature rules, and sample requests/responses.

Back to content

The order interface returns the transaction number and the payment data required for this payment. The key fields are as follows:

Field	Description
transactionId	PayCools Transaction Number
transactionStatus	Transaction status, e.g. pending
payData	Channel payment data, return QR code content/redirect link/virtual account by selected channel
cashierUrl	Repayment/Payment Instructions Page
channelType / channelCode	The channel type and channel code actually used this time

About payData (recommended)：payData Different types of content are returned depending on the product/channel:

• QR Channel: Returns the QR Content, which the merchant needs to render into a QR code image;
• VA/Billing Channels: Return to the virtual account (VA) or payment reference number, and the merchant shows the user to complete the transfer/payment;
• WebPay/eWallet Channels: Returns a jump URL that the merchant can direct the user to jump to or open using the button.

About cashierUrl：cashierUrl Provided by PayCools Repayment/Payment Guidelines Page, will display the corresponding payment guidelines based on the channel type:

• QR Channel: The QR code is rendered into a standard payment page by PayCools, and the user can pay by scanning the code;
• Jump to channel (WebPay/eWallet): Layer 1 forwarding by PayCools, eventually still redirects to payData channel address in, so the response time to the customer may be longer;
• VA Channels: Shows the user how to complete the repayment step using a virtual account.

Integration Suggestions: Preferred payData, the interaction is more direct - the QR content is rendered by itself, the jump link is directly to the channel, and the VA/reference number is displayed to the user; cashierUrl Applicable to scenarios (QR Rendering, Jump Forwarding, or VA Repayment Guidelines) where you wish to have a standard payment/instruction page rendered by PayCools.

6

Links that merchants need to handle on their own

Since the checkout page is implemented by the merchant itself, the following links need to be handled by the merchant themselves:

• Process payData: Process according to the return type - the QR content is rendered into a QR code, the jump URL is used for jumping, and the VA/reference number is displayed to the user.
• Pay Results Polling: After the user scans/jumps, the merchant needs to poll the call query interface to confirm the payment status.
• Payments Results Page: After the payment is completed, the user may jump back to the merchant side, and the merchant needs to display the corresponding success/failure page.
• Exception Handling: Handling of scenarios such as QR code expiration, payment failure, timeout and non-payment.

7

Integration Preparation

Before using the pure API model, make sure that:

1. at Merchant background completes public key configuration, get AppIDand ** Platform Public Key**
2. Understand Signature and verification mechanism, interface calls need to be carried in the request parameters sign
3. View Environmental information, confirm request address
4. Interface ready to receive asynchronous notifications of payment results (Notify URL)
5. Develop a checkout page with the ability to payData Type Ability to render QR codes/jump/show accounts, poll payment status, show payment results