Guides
Start typing to search…

Getting Started

Overview

Welcome to TocoPay API! This guide will help you quickly understand how to integrate the TocoPay payment system, including core features like deposits, withdrawals, and callback handling.

Quick Start (5 Minutes to Get Started)

If you want to start testing immediately, follow these steps:

1. Prepare Test Environment

# Test environment API URL
https://api.tocopay.net

# Test data you need
uid: "test1"                    # Test merchant account
api_secret: "your_test_secret"  # Test API secret
currency: "VND"                 # Test currency
pay_code: "812"                 # Test deposit channel

2. Quick Test Deposit Flow

  1. Get field rules: Call /channel/formRule API to get channel field requirements
  2. Create deposit order: Call /pay API to create deposit order
  3. Handle callback: Receive and process Webhook callback notifications

For detailed API call examples, please refer to Deposit API Documentation

3. Quick Test with Postman

  1. Download TocoPay API Postman Collection
  2. Configure environment variables: api_key, api_secret, base_url
  3. Run "Get Merchant Information" to test API connectivity
  4. Run "Create Deposit Order" to test complete flow

Note: Please ensure you have valid test merchant account and API secret. If not, please contact our technical support team to obtain them.

Step 1: Get API Credentials

1.1 Open Merchant Account

  • Visit TocoPay merchant management backend
  • Go to "System Management/System Information" menu
  • View channel information to get your merchant ID and API secret

Important Information:

  • uid: Your merchant account, used for all API requests
  • api_secret: API secret key for signature verification, keep it secure

Step 2: Understand Core Concepts

2.1 Deposit Channels (pay_code)

Deposit channels are different payment methods provided by TocoPay, each with a unique code.

How to get: Call /channel/query API with uid, currency, timestamp, userip and sign parameters to get all available deposit channels for that currency.

For detailed API documentation and response examples, please refer to Payment Form Fields API Documentation

Common deposit channel examples:

  • 812: Bank transfer
  • 1001: Credit card payment
  • 1036: E-wallet

2.2 Bank List (bank_id)

Some deposit channels require users to select a specific bank.

How to get: Call /channel/formRule API with uid, currency, pay_code, timestamp, userip and sign parameters, find the bank_id field in the returned form_fields, then get available bank list from the options array.

For detailed API documentation and response examples, please refer to Payment Form Fields API Documentation

2.3 Currency (currency)

Supported currency types, such as: VND, USD, INR, etc.

How to get supported currencies:

  1. Login to merchant management backend
  2. Go to "System Management/System Information" menu
  3. View supported currency list in wallet list

Step 3: Implement Signature Verification

3.1 Signature Algorithm

All API requests require signature verification, including the following steps:

  1. Collect all request parameters
  2. Sort by key name alphabetically
  3. Build signature string
  4. Add API secret
  5. Perform MD5 encryption and convert to uppercase

3.2 Signature Verification Points

  • Parameters must be sorted alphabetically (A -> Z)
  • Empty value parameters are ignored
  • Signature result must be uppercase
  • Timestamp uses Unix timestamp (seconds)

For detailed signature algorithm implementation and multi-language code examples, please refer to API Signature Documentation

Step 4: Create Deposit Order

4.1 Get Field Rules

Before creating a deposit order, first call /channel/formRule API to get the field requirements for that channel to ensure correct parameters are submitted.

For detailed API documentation and response examples, please refer to Payment Form Fields API Documentation

4.2 Create Deposit Order

Build deposit request based on field rules and call /pay API to create deposit order.

4.3 Handle Response

After successfully creating the order, it will return transactionid, payurl and other information. Users can complete payment through payurl.

For detailed API parameter descriptions and response examples, please refer to Deposit API Documentation

Step 5: Handle Webhook Callbacks

5.1 Receive Callback

When user completes payment, TocoPay will send callback to your notify_url containing status, result and sign parameters.

5.2 Callback Verification Points

  • Must verify signature to ensure data security
  • Judge transaction result based on status
  • Return success string to confirm receipt
  • Process business logic (update order, deliver goods, etc.)

For detailed callback handling process and multi-language code examples, please refer to Webhook Callback Documentation

Step 6: Withdrawal Function

6.1 Request Withdrawal

Call /applyfor API to request withdrawal, requiring bank account information and other parameters.

6.2 Withdrawal Callback Handling

Withdrawal callback handling is similar to deposits, also requiring signature verification and business logic processing.

For detailed withdrawal API parameter descriptions and callback handling, please refer to Withdrawal API Documentation

Step 7: Testing and Debugging

7.1 Test with Postman

For detailed Postman usage guide, please refer to Postman Guide

7.2 Debugging Tips

  • Log all API requests and responses
  • Log signature generation process
  • Use logs to record callback handling process
  • Monitor API response times

Environment Configuration

Production Environment

  • API URL: https://api.intqp.com
  • Purpose: Real transactions in production environment

Sandbox Environment

  • API URL: https://api.tocopay.net
  • Purpose: Testing and development

Important Reminders

  1. Security First: Keep API secret secure, don't expose it in frontend code
  2. Signature Verification: All requests must be signature verified
  3. Callback Handling: Asynchronous callbacks are the final result, don't rely on synchronous returns
  4. Error Handling: Implement comprehensive error handling and retry mechanisms
  5. Logging: Record key operations for troubleshooting

Next Steps

Frequently Asked Questions

Q1: How to get pay_code?

A: Call /channel/query API to get available channel list, get each channel's code from the response (e.g., 812, 1001, 1036, etc.)

Q2: How to get bank_id?

A: Call /channel/formRule API to get field rules, find the bank_id field in the returned form_fields, then get available bank list from the options array

Q3: What to do if signature verification fails?

A: Check the following points:

  • Is the API secret correct
  • Are parameters sorted alphabetically (A -> Z)
  • Is the timestamp format correct (Unix timestamp, seconds)
  • Is the signature result uppercase

Q4: What to do if callback is not received?

A: Check the following points:

  • Is notify_url accessible
  • Did you return the success string
  • Is the server accessible from the internet
  • Is there any firewall blocking

Q5: How to test callback functionality?

A: You can use the following tools:

  • ngrok: Expose local service to the internet
  • webhook.site: Online tool for temporarily receiving callbacks
  • Postman: Simulate callback requests

Q6: Deposit order creation failed?

A: Check the following points:

  • Did you first call /channel/formRule to get field rules
  • Are all required fields complete
  • Is the parameter format correct
  • Is the signature correct

Q7: How to get supported currencies?

A: Login to merchant management backend → System Management/System Information → View supported currency list in wallet list

Q8: What's the difference between test and production environments?

A:

  • Test Environment: https://api.tocopay.net, for development and testing
  • Production Environment: https://api.intqp.com, for real transactions

Contact Support

If you encounter issues during integration, please contact our technical support team.

Updated 4 months ago