Configuration and Signing

Last Updated: 2023-01-16 21:31:02

Get Merchant Account

After partnership confirmation, Payloco will verify KYC materials through our compliance review process. Once approved, you will receive an email notification. Please ensure your password is secure to prevent disclosure.

Get Merchant ID and Secret Key

The Merchant ID required for integration is available through the Merchant Management Dashboard. Signing uses the SHA256WithRSA algorithm. You need to generate public and private key pairs yourself and upload the public key through the Merchant Management Dashboard. Please keep your key information safe. If your key is compromised, update it immediately. Merchant Account:

Key Configuration:

Access the configuration: Merchant Management Dashboard → Developer → API Key menu.

Two-Factor Authentication (2FA) must be enabled before configuring keys.

Configure Webhook Notification

The webhook URL is used to receive asynchronous order callbacks from the Payloco server to your backend. This address can be submitted through API parameters or configured in the Merchant Management Dashboard. API parameter webhook URLs take priority over the dashboard settings. Access: Merchant Management Dashboard → Developer → Webhooks menu.

Webhook secrets can be viewed from the same location.

Viewing secrets requires login password verification

Public and Private Key Configuration

Purpose of Public and Private Keys

How to Generate Public and Private Keys

Merchant key pairs can be generated in three ways (choose any one). Please keep your private key safe for signing Payloco requests. Upload the public key to the Merchant Dashboard so Payloco can verify your signatures and prevent tampering during transmission. Obtain Payloco’s public key from the dashboard and use it in your system to verify Payloco’s signatures.

Generate Key Pair Online

Generate key pairs online using Payloco’s developer tools. The tool is pure JavaScript and does not communicate with Payloco servers, so your keys remain private.

Generate via SDK

The SDK provides a createKeyPair method or function in the development tools. Java SDK | PHP SDK

import java.security.*;

public class GenerateRSAKeyPair {
    public static void main(String[] args) throws NoSuchAlgorithmException {
        // Generate an RSA key pair
        KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("RSA");
        keyPairGenerator.initialize(2048); // You can change the key size as needed (2048 bits is recommended)
        KeyPair keyPair = keyPairGenerator.generateKeyPair();

        // Get the public and private keys
        PublicKey publicKey = keyPair.getPublic();
        PrivateKey privateKey = keyPair.getPrivate();

        // Print the keys (just for demonstration)
        System.out.println("RSA Public Key:");
        System.out.println(Base64.getEncoder().encodeToString(publicKey.getEncoded()));
        System.out.println("\nRSA Private Key:");
        System.out.println(Base64.getEncoder().encodeToString(privateKey.getEncoded()));
    }
}

Generate via OpenSSL

Generate PEM public and private key files using OpenSSL commands and manually remove headers, footers, and line breaks to get the key string. Download and install OpenSSL from: https://www.openssl.org/source/ Execute the following commands:

# Private key
openssl genrsa 2048 | openssl pkcs8 -topk8 -nocrypt -out private.key.pem
# Public key
openssl rsa -in private.key.pem -pubout > public.key.pem

After executing the above commands, two files will be generated as follows (example): Public key file public.key.pem:

Private key file private.key.pem:

Note: PKCS8 keys must have the header, footer, and line breaks removed.

Resulting public key string:

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzN6tx98b4KZB1uqEuT7P/nWHrYqFdiy+Kzs9KZ6JtSQWb3b45loOsdUxFeaCAt+ZJ0+fNJRDnwc7AiKOlgbw0HT93WRVZXP6cwQV1Bg1XybBxtQE4OcEq+Uzzmd7RoBkQuNmjIUgDYtWPBSekSpZAhWkk4dh8Nd7Qv2BvJNNOISVFcROFgMgbGz80v6WofR4nnTEdTB+j4pR/Q4dhnIROlaWrai+hBPn95sahQ+Ujf7LZgLyhpyQeS+/xsLv29lDI6D+8neR1tsOYdOp8f8QNwDkOroMlzxkQeYsJDLpLG8p58zHSdcLOsopVe2u41uzdrQ8qjhw4FU9eBOmFiteiwIDAQAB

Resulting private key string:

MIIEwAIBADANBgkqhkiG9w0BAQEFAASCBKowggSmAgEAAoIBAQDM3q3H3xvgpkHW6oS5Ps/+dYetioV2LL4rOz0pnom1JBZvdvjmWg6x1TEV5oIC35knT580lEOfBzsCIo6WBvDQdP3dZFVlc/pzBBXUGDVfJsHG1ATg5wSr5TPOZ3tGgGRC42aMhSANi1Y8FJ6RKlkCFaSTh2Hw13tC/YG8k004hJUVxE4WAyBsbPzS/pah9HiedMR1MH6PilH9Dh2GchE6VpatqL6EE+f3mxqFD5SN/stmAvKGnJB5L7/Gwu/b2UMjoP7yd5HW2w5h06nx/xA3AOQ6ugyXPGRB5iwkMuksbynnzMdJ1ws6yilV7a7jW7N2tDyqOHDgVT14E6YWK16LAgMBAAECggEBAKFLC8yZdixHGPzohHgH4N94jsptjae9kDcfG4dB3y8y60r0gv9wlbMiotOYOHGkssKFaFWQCTESEz4aEOJDMqMcCKaeELGgPuUAqWLjcFmqfNNaJ0EeAMqI2GG/jQmzmbwjpqApS1P+iHUi0rh9e7gta/YOl2hzbgMO7W6XFivQpMIQZQE0WpmpK8cNgev/Xog8ZnHFC6XGUgK+mDVvJMYwmywUPIfLw2fvAZ29QogtqiGeFCJSwAL1VkxryXSjJJBKuoc3cXEcq/hjhz6G9rvd50Lj2kCWMd8iqm/dtFyhDnT5WSFYNPIH0Up9qtqeP+TqgI/SrztAVHgUXVB2ABkCgYEA9cSeHG04Pj3p9ZCeCc6qb6L2kFphb62BhmUSHZ50p6X1KsSMw4wnzbrgrvcSe97iWZNLC536eQVHE5gL4ZjIxylYkp+FuuPHMIDseASR2pNmY2sJ83iTB4C9Y+37+64wBceFiXWBERdJA1t2MnzWLR8ijFfmHQ4KX3DJOhR05qUCgYEA1WYroahttPyvMFHdmcCphF9jhF3U6SGuVndwTtqaGLHzCmSvHxLFyd8ziw/F344IGIn8fIbOqhFAijyliD53kGMiKSUqMH4QeP2RfxGrZqek3f6pvyUtxfjXAh6+7pfL46u0AzmyvcpaGXqQToecCF43MCdbxh7Z3CViGfBcWW8CgYEAvJRcufU4ddHuJoYMLfxNHRIPXV5sa1PYEjaVevKuEkGuaF2eoSF3HU4qvzZIEZJJXnA94jEbEydwjWFapIUmcmOQWhlbdLb4jYgvajwfanc11k04uoAnWVd4eygN9OWIZbbeCUaHfYS/ensAq+bMNJ0yVjvQDzVJ0kfpr84okR0CgYEAmBroNKTx9ZQ6Zu2jT2lVKuY27+1VygpY0ob1xS7psXp9asYTUMm3s0ll2tQWTV9Wg+8uya/o9K2xXBcYQgGMhZ0zhzJXXRMuOJ88qt70VgpeaGGRqo4cj0TsNDWoEDagfJoxiC8DKWZnTEvhOihM3mYRXkBfmNr6nIEE6Mo7eP8CgYEA8KqzIk+5On3xmeESfQcLPYiaO9Hlttc7flyIpUL52Og7S1T/ekdiBVIDlePpjRx5H0iCtANyWmQq0XbfSseQ9SFJ/4DLvDMawhvolmxHs98PNa8xZ9KdXgUNc7RcewUVhK2aLkxUQKNO0lwwGGDGWfvePWzlVotJd0bM+a/X4qg=

The request body string used for signing with the merchant private key must be identical to the string in the HTTP body. Different formatting will produce different signatures and cause Payloco signature verification to fail. For example, the two JSON strings below have the same meaning but will produce different signatures due to formatting differences. You can use the developer Self-Service Signing Tool to experience the signing process.

Formatted JSON string:

{
    "key1":"val1",
    "key2": "val2",
    "key3": "val3"
}

Signature result using sample private key:
"FPFVT3o227JrFRbqu19boZCpVVTF9KznxyRawUmxpfXilHV/0yK46haPhAjNu1hPUMy7Vw/ILXhfzffNm4Fj0apWknlTY9OJxnSoQxS9BTFtc61tn5yV1q69x/kkBl82/qwg+XTJ4fOzy7Mar3VaC1E2PlDA6RkkKBUyNE6RYgsdB+Su7an4+4HVTNAnoe74WyvBgxTLMNg28igBTdqxaO3w/UBY6ObVp7vkqkQGdL1Y+HgmMYaAVwrM3+ALWGId0sJ+YqTY4WJ+0xCRGhaSnybiIjZsQEYyID68WNUfuavDLDsEhaMm/HfQvf5p0R1Ltovp3wwJnEbQcjY458iX5A=="

Compact JSON string:

{"key1":"val1","key2":"val2","key3":"val3"}

Signature result using sample private key:
"W/unZQUH9366PZDhYlCghA7q66VmPDBN/7OvVKhigQNfLJPxGnbhrH6JV4rYlsyfduPt4QKZalaafvs/tJ+CVOr2RGt3815hcAPB7MN/u4y3W+IfbwTXkT7gWujT652YDfMls2dwRCYun++DSOVFHkP8FUp8/Rb6e8CuKbA40RwfHfUTek24TMq0JmiYZDfRYbMUE30Pm8PXDAStoTTOqjJ+5zVAMWCzUwId1/P3iNWue+DUwCyLEA6tHFIJX8dUoSlbtjRs1p4Q8ahSFg5Dx+RORtLclnp8g38hgWFNsvcSuW3RXTkwIYmmbp5Qguw16af9P8Li82zI4M8TqgI08g=="

Signature Algorithm

Type	Description
Algorithm	RSA
Key Format	PKCS8
Sign Method	SHA256WithRSA
Key Length	2048

Sample Messages

Request message

POST https://gate.payloco.com/gateway/v1/payments/open/api/pay
Content-Type:application/json
Content-Length:580
sign: Sign request body with merchant private key

{
    "charset": "UTF-8",
    "version": "2.0.0",
    "requestTime": "2022-01-17T08:04:13.879+00:00",
    "memberId": "3b242b56a8b64274bcc37dac281120e3",
    "merchantId": "020213827212251",
    "data": {
        "outTradeNo": "Pay1642406653879",
        "subject": "MacPro14 and Mouse",
        "totalAmount": "10000",
        "currency": "IDR",
        "country": "ID",
        "userId": "10001",
        "language": "en",
        "reference": "020213827524152",
        "frontCallbackURL": "https://www.payloco.com",
        "notifyUrl": "https://www.payloco.com"
    }
}

Response message

POST https://gate.payloco.com/gateway/v1/payments/open/api/pay
Content-Type:application/json
Content-Length:580
sign: Sign request body with merchant private key

HTTP/1.1 200 OK
Date:Mon, 17 Jan 2022 03:49:08 GMT
Content-Type:application/json
Connection:keep-alive
sign: Payloco signature — verify using response JSON body and Payloco public key

{
    "code": "00000000",
    "message": "Success",
    "data": {
        "redirectUrl": "https://cashier-n.payloco.com/index.html#/cashier/home?merchantId=020213827212251&appId=3b242b56a8b64274bcc37dac281120e3&country=ID&tradeToken=TOKEN20220117080414618354880&language=en&token=LVDNgrtBcAvo0W6Zjhuons2jfZsEJXgFIAFDLf2Tq2I2FkdUhwF%2Fm8lxxmI1%2BVPfbPafUGFbZfTqagFOD3mMOAKm6790AZi7nuoQbG7SWFIyfD7hr0LbAy9TUpJNjm%2Bsxg2O%2FGvFpzpwP3P1JZxA%2BEajse7sQQubFZhFNGK9o9I%3D&amount=10000&currency=IDR&frontCallbackUrl=https%3A%2F%2Fwww.baidu.com",
        "outTradeNo": "Pay1642406653879",
        "tradeToken": "TOKEN20220117080414618354880",
        "status": "PENDING"
    }
}

Developer Guide

Global Acquiring

Global Payment

Async Notifications

Appendix

Get Merchant Account

Get Merchant ID and Secret Key

Configure Webhook Notification

Public and Private Key Configuration

Purpose of Public and Private Keys

How to Generate Public and Private Keys

Generate Key Pair Online

Generate via SDK

Generate via OpenSSL

Signature Algorithm

Sample Messages

​Get Merchant Account

​Get Merchant ID and Secret Key

​Configure Webhook Notification

​Public and Private Key Configuration

​Purpose of Public and Private Keys

​How to Generate Public and Private Keys

​Generate Key Pair Online

​Generate via SDK

​Generate via OpenSSL

​Signature Algorithm

​Sample Messages

Get Merchant Account

Get Merchant ID and Secret Key

Configure Webhook Notification

Public and Private Key Configuration

Purpose of Public and Private Keys

How to Generate Public and Private Keys

Generate Key Pair Online

Generate via SDK

Generate via OpenSSL

Signature Algorithm

Sample Messages