DOCSEARCHbyAlgolia
Submit Docs

VamosPago Developer Documentation

website·Indexed 31 days ago

https://doc.vamospago.com

Integration guidelines and OpenAPI 3.0.1 specifications for VamosPago payment and payout services. Includes documentation on API request structures, signature algorithms, webhooks, order status state machines, PCI DSS compliance, and regional transaction configurations for North America, South America, and Asia.

Tokens
70.9K
Snippets
285
Records
341
Agent score
51%

What's inside VamosPago

  1. Understand PCI DSS compliance requirements for vamospago users

    The Payment Card Industry Data Security Standard (PCI DSS) applies to all companies that accept, process, store, or transmit credit card information. Even when using a third-party provider like vamospago to handle cardholder data, merchants are still required to undergo the certification process annually. While third-party solutions reduce the effort and expense of compliance, they do not eliminate the requirement entirely.

  3. Execute a Payout via the /gateway/base/biz endpoint

    Use the POST /gateway/base/biz endpoint to initiate a payout.

    Critical Requirements:

    • Mobile Numbers: Must include a three-digit country code (e.g., 254700538015).
    • Wallet Accounts: Must start with the country code (e.g., 254xxxxxxxxx).
    • Bank Codes: The beneficiaryBankCode is mandatory when paymentType is set to NET_BANKING.
    # Request Headers
method: payOut
signType: SHA512
serviceName: api.pay
mchId: '1416010331032883200'
timestamp: '1631671670'
sign: '32554324534545432543'

# Request Body (application/json)
{
  "mchOrderId": "string", // Min 5, Max 32 chars
  "amount": "string",
  "currency": "USD",
  "purpose": "string",
  "beneficiaryName": "string",
  "beneficiaryEmail": "string",
  "beneficiaryMobile": "string",
  "beneficiaryAccountNumber": "string",
  "callbackUrl": "string",
  "paymentType": "NET_BANKING",
  "docType": "MPESA", // Options: MPESA, AIRTEL
  "beneficiaryBankCode": "000001" // Required for NET_BANKING
}

  4. Execute a Payout via the /gateway/base/biz endpoint

    To perform a payout, send a POST request to /gateway/base/biz. This endpoint is used for transaction processing in Asia/Pakistan.

    Critical Requirements:

    • Phone Numbers: Must start with 03 and contain exactly 11 digits (e.g., 03XXXXXXXX).
    • Beneficiary ID: Must be a valid existing ID. Avoid using fixed values for IDs to prevent triggering risk control systems.

    Mobile Operator Prefixes for Validation:

    • 364: Instaphone
    • 300, 301, 302, 303, 306, 307, 308: Mobilink
    • 314: ZONG (includes former 304 Paktel GSM)
    • 342, 343, 344, 345, 346: Telenor
    • 321, 322, 323: Warid Telecom
    • 331, 332, 333, 334, 335: Ufone
    • 312, 313: ZONG
    curl -X POST "https://[api-domain]/gateway/base/biz" \
  -H "method: payOut" \
  -H "signType: SHA512" \
  -H "serviceName: api.pay" \
  -H "mchId: YOUR_MERCHANT_ID" \
  -H "timestamp: 1631671670" \
  -H "sign: YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "mchOrderId": "ORDER12345",
    "amount": "100.00",
    "currency": "USD",
    "purpose": "Product Description",
    "beneficiaryName": "John Doe",
    "beneficiaryMobile": "03001234567",
    "beneficiaryAccountNumber": "123456789",
    "paymentType": "WALLET",
    "beneficiaryBankCode": "033"
  }'

  5. Initiate a Payout via the /gateway/base/biz endpoint

    To initiate a payout, send a POST request to /gateway/base/biz.

    Important Requirements for Mexico Payouts:

    • Payment Types:
      • For SPEI, the beneficiaryAccountNumber must be a CLABE number.
      • For NET_BANKING, the beneficiaryAccountNumber should be the bank card number.
    • Status Behavior: Mexico payouts default to a successful callback. If the account is abnormal or incorrect, the order status will transition from SUCCESS to REVERSED.
    curl -X POST "https://[api-domain]/gateway/base/biz" \
  -H "method: payOut" \
  -H "signType: SHA512" \
  -H "serviceName: api.pay" \
  -H "mchId: 1416010331032883200" \
  -H "timestamp: 1631671670" \
  -H "sign: 32554324534545432543" \
  -H "Content-Type: application/json" \
  -d '{
    "mchOrderId": "ORDER12345",
    "amount": "100.00",
    "currency": "USD",
    "purpose": "Product description",
    "beneficiaryName": "John Doe",
    "beneficiaryAccountNumber": "CLABE_OR_CARD_NUMBER",
    "beneficiaryBankCode": "40012",
    "callbackUrl": "https://your-webhook.com/callback"
  }'

  6. Bind Google Authenticator 2FA for merchant accounts

    Newly registered merchants are required to bind 2FA verification to secure their accounts. To complete the binding process:

    1. Click on the 【Username】 located in the upper right corner of the interface.
    2. Select 【Reset 2FA Code】.
    3. Use the Google Authenticator app to scan the displayed QR code.
    4. Enter the generated dynamic code to finalize the binding.

    Important: Keep your 2FA keys and account passwords secure. The platform is not responsible for fund losses resulting from leaked 2FA codes or passwords.

  7. Initiate a Payout via the /gateway/base/biz endpoint

    Use the POST /gateway/base/biz endpoint to initiate a payout.

    Formatting Requirements:

    • Mobile Numbers: Must include a three-digit country code (e.g., 254700538015).
    • Wallet Accounts: Must start with the country code (e.g., 254xxxxxxxxx).

    Request Headers:

    • method: Interface method (e.g., payOut).
    • signType: Signature type (e.g., SHA512).
    • serviceName: Service name (e.g., api.pay).
    • mchId: Merchant ID.
    • timestamp: Current timestamp in seconds.
    • sign: The generated signature.

    Request Body (JSON):

    • mchOrderId: Merchant order number (5-32 characters).
    • amount: Order amount in currency units.
    • currency: Three-letter currency code (e.g., USD).
    • purpose: Product description.
    • beneficiaryName: Name of the beneficiary.
    • beneficiaryEmail: Email of the beneficiary.
    • beneficiaryMobile: Mobile number of the beneficiary.
    • beneficiaryAccountNumber: Account number of the beneficiary.
    • callbackUrl: Webhook URL for notifications.
    • paymentType: Payment type (e.g., NET_BANKING).
    • beneficiaryBankCode: Required when paymentType is NET_BANKING.
    POST /gateway/base/biz
Content-Type: application/json
method: payOut
signType: SHA512
serviceName: api.pay
mchId: 1416010331032883200
timestamp: 1631671670
sign: 32554324534545432543

{
  "mchOrderId": "ORDER12345",
  "amount": "100.00",
  "currency": "USD",
  "purpose": "Payment for services",
  "beneficiaryName": "John Doe",
  "beneficiaryMobile": "254700538015",
  "paymentType": "NET_BANKING",
  "beneficiaryBankCode": "000001",
  "callbackUrl": "https://your-webhook.com/callback"
}

  9. Payment API request requirements

    To process a payment via the /gateway/base/biz endpoint, the following parameters are required in the request body:
    {
  "mchOrderId": "string",
  "amount": "number",
  "firstname": "string",
  "currency": "string",
  "lastname": "string",
  "productinfo": "string",
  "email": "string",
  "phone": "string",
  "callbackUrl": "string",
  "redirectUrl": "string",
  "noPayPage": "string"
}

  10. Implement Vamospago API integration

    Follow these steps to integrate Vamospago payment and payout services:

    1. Signature Rules: Review the API Signature documentation to implement request signing.
    2. Core Transactions: Integrate the collection and payout APIs specific to the target region.
    3. Webhooks: Configure the webhook URL during the order placement call in the transaction API.
    4. Common APIs: Implement the Order Status Query and Account Balance Query endpoints.
    5. Validation: Refer to the 'Payment of Video Case' for practical implementation examples.

  11. Payout request requirements

    The Payout API requires a set of mandatory fields to process a transaction. In addition to common request body parameters, the following fields are required: paymentType, docType, beneficiaryBankCode, firstName (Beneficiary's first name), and lastName (Beneficiary's last name).

  12. Process payments using PSE HPP (Hosted Payment Page)

    The PSE HPP flow is used for CVU payments. The merchant provides a checkout payment page showing a CVU account number. The user copies this number and performs a transfer via their Bank or Wallet. After the transfer, the user submits the bank reference number on the checkout page. Vamospago then maps the user-submitted reference number against the callback received from the PVS (Payment Verification System). If the reference numbers and amounts match, Vamospago sends a callback to the merchant with the order result.