Integration Preparation & Security

Before integrating with Ayoconnect's payment APIs, merchants must complete the required security configurations to ensure secure communication, authentication, and transaction processing in accordance with the applicable SNAP (Standar Nasional Open API Pembayaran) specifications.

IP Whitelisting

Ayoconnect uses IP whitelisting as an additional security measure to restrict API access to authorized sources.

Merchants are required to prepare and register their public server IP addresses with Ayoconnect before initiating API requests, where IP whitelisting is applicable.

Two types of IP configuration should be considered:

Sandbox and Production environments may have different IP configurations.

Please coordinate with the Ayoconnect integration team to register and verify the applicable IP addresses.

API Credentials & Authentication

Ayoconnect implements OAuth 2.0-based access tokens and digital signatures to authenticate and validate API requests.

Merchants will receive the necessary integration credentials during onboarding, including the applicable Client ID, Client Secret, Partner ID, Channel ID, and key-registration requirements.

B2B Access Token

The B2B Access Token authenticates the merchant when accessing Ayoconnect APIs.

Merchants must generate a B2B Access Token before making protected API requests and include it in the Authorization header.

The token can be reused until its expiration and should be renewed when necessary.

Reference: Generate B2B Access Token API

B2B2C Customer Authorization Token

For customer-specific operations, such as Direct Debit payments, merchants are also required to provide a B2B2C Customer Authorization Token.

The B2B2C token represents customer-specific authorization and is generated using the customer's authorization code (authCode) obtained during the binding process.

For applicable transactions, merchants must include the token in the Authorization-Customer header alongside the B2B token.

Reference: Generate B2B2C Customer Authorization Token API

Request Signature & Validation

To maintain request authenticity and integrity, Ayoconnect implements digital signature validation in accordance with the applicable SNAP API specifications.

• Access Token Generation: Uses RSA-SHA256 asymmetric digital signatures.
• Transactional APIs: Use the required request signature mechanism, such as HMAC-SHA512, depending on the API specification.
• Request Validation: Merchants must provide the required authentication tokens, timestamp, signature, and transaction identifiers.

Merchants should ensure that their server timestamps are synchronized and that every API request follows the header and signature specifications defined in the respective API Reference.

Callback Configuration

Merchants must prepare HTTPS callback endpoints to receive asynchronous transaction notifications from Ayoconnect.

Before going live, ensure that:

• Callback URLs are registered with Ayoconnect.
• Ayoconnect's callback IP addresses are allowlisted where applicable.
• Callback endpoints are accessible and use valid HTTPS certificates.
• Callback requests are handled securely and return an appropriate HTTP 2xx response after successful receipt.

For product-specific callback behavior, retry mechanisms, and response formats, refer to the corresponding Callbacks documentation.

Integration Readiness

Before proceeding to Production, merchants should ensure that IP whitelisting, API credentials, digital signatures, authentication tokens, and callback endpoints have been successfully configured and tested in Sandbox.

Production credentials and configurations must be managed separately from Sandbox.

For further assistance with integration preparation, contact the Ayoconnect integration team.