Sending Payments

​

Sending a Payment

curl -X POST https://api.platnova.com/v1/payments/send \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_amount": 500.00,
    "from_wallet_id": "wl_your_wallet_id",
    "to_currency": "NGN",
    "payment_method": "bank_transfer",
    "info": {
      "account_number": "0123456789",
      "bank_code": "058",
      "account_name": "Jane Smith"
    },
    "reference": "PAY001",
    "payment_type": { "type": "instant" }
  }'

​

Payment Parameters

​

Required Fields

• from_amount – Amount to send (source currency)
• from_wallet_id – Wallet ID to debit from
• to_currency – Destination currency (e.g. NGN, USD)
• payment_method – One of: bank_transfer, card, mobile_money, wallet, tag_transfer, defi, revolut, paypal, cashapp, zelle
• info – Recipient details; required fields depend on payment_method (e.g. for bank_transfer: account_number, bank_code, account_name; for tag_transfer: tag_id)

​

Optional Fields

• reference – Your payment reference for idempotency or tracking
• payment_type – instant, scheduled, or recurring (default: instant)
• is_save_to_beneficiary – Save recipient as beneficiary

​

Finding the bank_code

1. GET /v1/banks/{country_code} lists every bank with its code.
2. For Ghana and Kenya, GET /v1/banks/{country_code}/{bank_code} lists branches; pass the chosen branch_code in info.branch_code.
3. POST /v1/banks/verify resolves the account number to the holder’s name before you send.
4. If you only have an account number, POST /v1/banks/suggest returns banks we have paid it through before.

​

Payment Response

{
  "status": true,
  "data": {
    "transaction_id": "txn_123",
    "payment_reference": "PAY001",
    "amount": "500.00",
    "currency": "USD",
    "recipient_account_number": "1234567890",
    "recipient_name": "Jane Smith",
    "status": "processing",
    "created_at": "2025-01-30T10:00:00Z"
  },
  "message": "Payment initiated successfully"
}

​

Payment Status

• Processing - Payment is being processed
• Success - Payment completed successfully
• Failed - Payment failed (check error details)

​

Verifying Payment Status

curl -X POST https://api.platnova.com/v1/payments/verify \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "UTR_xxxx"
  }'

​

Payment Methods

​

Payment Limits

• Account tier
• Currency
• Payment method
• Regulatory requirements

​

Payment Fees

• Payment amount
• Currency
• Payment method
• Destination country

​

Best Practices

• Verify recipient account details before sending
• Include payment references for easy tracking
• Monitor payment status regularly
• Keep sufficient wallet balance
• Handle failed payments appropriately

​

Next Steps

• Learn about Payment Verification for checking payment status
• Explore the Payments API Reference for detailed documentation