SuwPay Payment OPEN API (1.0.0)

The SuwPay Payment Open API provides comprehensive collection and disbursement services for merchants, supporting multiple payment channels and currencies. Through standardized interface specifications, merchants can efficiently integrate payment functionalities to achieve secure, fast fund transfers and management.

• All timestamps use standard UTC time format (e.g., 2025-03-05T09:21:53.661Z)
• Indonesian channels only support integer amounts

The SuwPay Payment Open API uses OAuth 2.0 standard with Bearer Token authentication. Merchants must provide valid Bearer Tokens in request headers to access API endpoints.

After account creation, merchants can obtain Access Tokens from the SuwPay Dashboard. Securely store and regularly rotate tokens.

RSA signature verification is disabled by default. Merchants enable it by uploading their public key via the SuwPay Dashboard. SHA256WithRSA signature algorithm is used for signature. Merchants generate their own public and private key pairs, upload the public key via the SuwPay Dashboard, and download SuwPay's public key. Ensure that the keys are stored securely. If a key is compromised, update it immediately.

Signature requires two parameters: RSA private key and raw request body string (without sorting). For empty bodies, use empty string "". Finally, perform Base64 encoding on the encrypted byte data.

Signature Example

import java.security.*;
import java.security.spec.PKCS8EncodedKeySpec;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;

public class RSAUtil {

    // Generate a key pair
    public static KeyPair generateKeyPair() throws NoSuchAlgorithmException {
        KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("RSA");
        keyPairGenerator.initialize(2048); // Key size can be adjusted as needed
        return keyPairGenerator.generateKeyPair();
    }

    // Sign data using the private key
    public static String signData(String data, PrivateKey privateKey) throws Exception {
        Signature signature = Signature.getInstance("SHA256withRSA");
        signature.initSign(privateKey);
        signature.update(data.getBytes());
        byte[] signedData = signature.sign();
        return Base64.getEncoder().encodeToString(signedData);
    }

    // Verify signature using the public key
    public static boolean verifySignature(String data, String signedDataBase64, PublicKey publicKey) throws Exception {
        byte[] signedData = Base64.getDecoder().decode(signedDataBase64);
        Signature signature = Signature.getInstance("SHA256withRSA");
        signature.initVerify(publicKey);
        signature.update(data.getBytes());
        return signature.verify(signedData);
    }

    // Get the public key as a string (for storage or transmission)
    public static String getPublicKeyString(PublicKey publicKey) {
        return Base64.getEncoder().encodeToString(publicKey.getEncoded());
    }

    // Restore the public key from a string
    public static PublicKey getPublicKeyFromString(String publicKeyString) throws GeneralSecurityException {
        byte[] publicKeyBytes = Base64.getDecoder().decode(publicKeyString);
        X509EncodedKeySpec keySpec = new X509EncodedKeySpec(publicKeyBytes);
        KeyFactory keyFactory = KeyFactory.getInstance("RSA");
        return keyFactory.generatePublic(keySpec);
    }

    // Get the private key as a string (for storage or transmission; ensure security)
    public static String getPrivateKeyString(PrivateKey privateKey) {
        return Base64.getEncoder().encodeToString(privateKey.getEncoded());
    }

    // Restore the private key from a string
    public static PrivateKey getPrivateKeyFromString(String privateKeyString) throws GeneralSecurityException {
        byte[] privateKeyBytes = Base64.getDecoder().decode(privateKeyString);
        PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(privateKeyBytes);
        KeyFactory keyFactory = KeyFactory.getInstance("RSA");
        return keyFactory.generatePrivate(keySpec);
    }

    // Main method (for testing only)
    public static void main(String[] args) {
        String privateKeyString = "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC8X9hru/AR0DeFOzyQeDTPpYOT4u5fJDQGu5G5K2YFUVK/471XSIk7zQzLexW2at1XQWn8cZgF4aDJiLt1FvQYNpiNWAlxSOLEa4MnAkvEeU30PKmcxMjCWdlC3Rk4VVpqLqBB6Ovfb+Z0Ea7u9XITfUaOb1A71klkdyppPMYV2uvXa9UAC5BtNMnstpe2ZU8Omw1bfjRZT6YpuJEbDt9Xy8S4bqhhrsSTQFYxLXjKNr2ZhtweDndKc8ZhwDhNE2Tw2pAH9A3tO1aV5blcHcj0xw2Lqt4QoSZWTlIxjGN5oQ0C+B9G7VsFgloLkjxIroGsRQazZzLTLT0oh9MsmRtXAgMBAAECggEACWkYXLl00s7+Fw/QhL8clEsGebragbJDTxrLut5qKFXZtnBgIx4ijPQ/cWLiwMwx5owECXJ7T7/n0mmcQ8szwonnsRf20Mv9WCau1KIOuu/8bvkg2A4UoXDvo6F8Aw5wh+FwbBqAvhbPAnlnrdRhMIwPnEn/Th30aKpzWfKJSsog9tbc/au9/gDGWPUfcDlPuH1IFSN0Z6KbeCEeSsCDXz68jhOdLjUtZE+4Hvp3ZbNL4YOToQY1lQWtw1VdJRzyjtZCZPaeviXiQTuIo52s5AV2ZhFdHa9HWD0IuXV12SBFlpi1u1hk1W5m4T3KMrErooOFCa7hynNXM6ofBMJzEQKBgQDx5Yx6tXsiQKukShWKkaWly8ozYqf2V42jkrAFy3XLqdYeNBso1Qb3l2u2C7xG1z/3QyNCBlp7m8YDd+0Jl4Ldp13P87LKvRes1MidIkHEzEIfTNyyXXXn3FZMbU5qEDMggL1gBlD2fS4UgxQ/HBgXJc9+BSdDmiLFfKh3DQY7iwKBgQDHW3HlvmMa/2/xHH5Nn+ub++VLASlRUC7sU24BE/PtEllwWDZ4DpUQ5OlkCleE0cGjFnh3zC6yZgSmN02X6wpghVF9/Vf2B+ZUSBbdbSDxGmrIH9wnFTDLGmOKB1DzbGQsFsVG/TMh7UGjPB/jzWY5cgn6HwI0PXzPowL2P6yI5QKBgBjlUCz86pxe3Yt+GHN3g/3pWHkraTAAWNKB8V3XT9tTMndPU5BDRIFM80f8MzdzReET5tgPwVZBdQK8YAgBsPVRGWWipj8ZcQtXpwINGYnAn/mKtpgg6Fahpbwd79kYq7pnpZXxcHm97nUr/HR2VsBjItTMgPsDLRr4NnpyO7b7AoGBAKfv+Lq473PGyt4qSpvJpAj64eWVTOEa0uxyO7Dcxhdn5cAmD3yDjD93FsUXkTJqINzqCQGiF5RhLHl5DPx1G4DDzip8SKURco59TAWr8JwqzNlZPXQO/dOan0+faiolnR0m8XkjwvdJjomcFKEqXnr1/kGd7ZVkVsfzYoNekFGhAoGAYS2R8jT2byKu/3rukAog0zYe++aqq3naSiSxpLPuM1S74GomjiSYCNTZkEXd+QXzaIMXjG+t4MbHca244AUUPl8sMA49M3h+48hHBw7bS+7kvXgWpQbgujnQg6C/RkqG49xV3cm6W+tC/aodScrU1RWkbRg7hvJhMuv1TfSipWo=";
        /* Note: The request body is unordered; do not sort it before signing or verifying. */
        String body = "{    \"merchantNo\": \"MCHID20250101000000A1A1\",    \"appId\": \"APP20250101000000P1P1\",    \"timestamp\": \"1740108488586\",    \"version\": \"1.0\",    \"data\": {        \"merchantRequestNo\": \"test00000001\",        \"currency\": \"IDR\",        \"country\": \"ID\",        \"amount\": 10000,        \"paymentMethodCode\": \"IDR_QRIS\",        \"paymentTargetOrg\": \"IDR_QRIS\",        \"subject\": \"Purchase of Goods\",        \"description\": \"Payment for electronic goods\",        \"language\": \"en\",        \"payerInfo\": {            \"email\": \"johndoe@example.com\", \"phoneNo\": \"+1234567890\"        }    }}";
        try {
            PrivateKey privateKey = getPrivateKeyFromString(privateKeyString);
            String signedData = signData(body, privateKey);
            System.out.println(signedData);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Callback Signature Verification

Callbacks don't include signatures by default. Uploading merchant public key via the SuwPay Dashboard enables callback signatures (marked as "Sign" in the header). Merchants can choose whether to verify the signature for payment callbacks. The signing process involves signing the request body string directly without sorting. Verification should also be performed on the request body string without converting it into an object first.

Header

Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cC...
Sign: MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr...

Body

{
  "merchantNo": "MCH12345",
  "appId": "APP67890",
  "timestamp": "2023-10-15T08:55:30Z",
  "version": "1.0",
  "data": {}
}

Header

Body

{
  "status": "success",
  "code": 201,
  "message": "Transaction successfully created",
  "data": {
      // Specific business data
  },
  "errors":[]
}

Error Example:

{
  "status": "error",
  "code": 422,
  "message": "Business rule errors",
  "errors": [
    {
      "code": "UNSUPPORTED_CURRENCY",
      "message": "Unsupported currency type",
    }
  ]
}

After a payment order is completed (the payment order status is final, indicating success or failure), SuwPay will send the relevant payment result to the merchant, The merchant is required to receive and process the notification, returning a response as per the documentation.

Header

Content-Type: application/json
Sign: MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAt...

Body

{
  "data": {
      "suwpayOrderNo": "Test1645780876511",
      "merchantRequestNo": "Test1645780876511",
      "amount": "10000.00",
      "currency": "IDR",
      "status": "paid",
      "createdTime": "2023-10-15T08:55:30Z",
      "paymentMethodCode":"ID-VA",
      "paymentTargetOrg":"BRI",
      "paymentReceiveAccount":{
        "accountType":"va_number"
        "accountName":""
        "vaNumber":"8916900133279954",
        "qrString":"",
        "redirectUrl":""
      }    
      "paidTime":"2023-10-15T09:36:00Z"
    },
    "errors":[]
}

Callback Response and Retry

After SuwPay sends a callback notification to the merchant, the merchant should respond with a 200 status code promptly. If a non-200 HTTP response is received, SuwPay will automatically retry every 5 minutes until the merchant responds with a 200 HTTP status code. SuwPay will retry a maximum of 3 times for each callback notification.

Collection(VA)

{
    "merchantNo": "MCHID20250101000000A1A1",
    "appId": "APP20250101000000P1P1",
    "timestamp": "2025-03-05T09:47:33.857Z",
    "version": "1.0",
    "data": {
        "merchantRequestNo": "test00000001",
        "currency": "IDR",
        "country": "ID",
        "amount": 10000,
        "paymentMethodCode": "IDR_VA",
        "paymentTargetOrg": "BRI",
        "subject": "Purchase of Goods",
        "description": "Payment for electronic goods",
        "language": "en",
        "payerInfo": {
            "email": "johndoe@example.com", "phoneNo": "+1234567890"
        }
    }
}

Collection(QRIS)

{
    "merchantNo": "MCHID20250101000000A1A1",
    "appId": "APP20250101000000P1P1",
    "timestamp": "2025-03-05T09:47:33.857Z",
    "version": "1.0",
    "data": {
        "merchantRequestNo": "test00000001",
        "currency": "IDR",
        "country": "ID",
        "amount": 10000,
        "paymentMethodCode": "IDR_QRIS",
        "paymentTargetOrg": "IDR_QRIS",
        "subject": "Purchase of Goods",
        "description": "Payment for electronic goods",
        "language": "en",
        "payerInfo": {
            "email": "johndoe@example.com", "phoneNo": "+1234567890"
        }
    }
}

Collection(EWALLET)

{
    "merchantNo": "MCHID20250101000000A1A1",
    "appId": "APP20250101000000P1P1",
    "timestamp": "2025-03-05T09:47:33.857Z",
    "version": "1.0",
    "data": {
        "merchantRequestNo": "test00000001",
        "currency": "IDR",
        "country": "ID",
        "amount": 10000,
        "paymentMethodCode": "IDR_EWALLET",
        "paymentTargetOrg": "DANA",
        "subject": "Purchase of Goods",
        "description": "Payment for electronic goods",
        "language": "en",
        "payerInfo": {
            "email": "johndoe@example.com", "phoneNo": "+1234567890"
        }
    }
}

Disbursement(BANK)

{
  "merchantNo": "MCHID20250101000000A1A1",
  "appId": "APP20250101000000P1P1",
  "timestamp": "2025-03-05T09:47:33.857Z",
  "version": "1.0",
  "data": {
    "merchantRequestNo": "test00000001",
    "currency": "IDR",
    "country": "ID",
    "amount": 10000,
    "paymentMethodCode": "IDR_BANK_TRANSFER",
    "paymentTargetOrg": "Bank BRI",
    "recipientInfo": {
      "name": "123456789",
      "accountNo": "123456789"
    }
  }
}

Disbursement(EWALLET)

{
  "merchantNo": "MCHID20250101000000A1A1",
  "appId": "APP20250101000000P1P1",
  "timestamp": "2025-03-05T09:47:33.857Z",
  "version": "1.0",
  "data": {
    "merchantRequestNo": "test00000001",
    "currency": "IDR",
    "country": "ID",
    "amount": 10000,
    "paymentMethodCode": "IDR_EWALLET_TRANSFER",
    "paymentTargetOrg": "DANA",
    "recipientInfo": {
      "name": "123456789",
      "accountNo": "123456789"
    }
  }
}