๐Ÿ”Standard Integration

Overview

Moneroo Standard is our "standard" payments flow that redirects your customer to a Moneroo-hosted payments page.

Here's how it works:

  • From your server, call our API initialize payment endpoint with the payment details.

  • We'll return a link to a payment page. Redirect your customer to this link to make the payment.

  • When the transaction is completed, we'll redirect the customer back to you (to the return_url you provided) with the payment details.

Step 1: Collect payment details

First, you need to assemble payment details that will be sent to your API as a JSON object.

Here fields you need to collect:

Field NameTypeRequiredDescription

amount

integer

Yes

The payment amount.

currency

string

Yes

The currency of the payment.

description

string

No

Description of the payment.

return_url

string

Yes

Return URL where your customer will be redirected after payment.

customer.email

string

Yes

Customer's email address.

customer.first_name

string

Yes

Customer's first name.

customer.last_name

string

Yes

Customer's last name.

customer.phone

string

Noยน

Customer's phone number.

customer.address

string

Noยน

Customer's address.

customer.city

string

Noยน

Customer's city.

customer.state

string

Noยน

Customer's state.

customer.country

string

Noยน

Customer's country.

customer.zip

string

Noยน

Customer's zip code.

metadata

array

Noยฒ

Additional data for the payment.

methods

array

Noยณ

Payment method you want to make available for this transaction.

  1. If not provided, the customer can be prompted to enter these details during the payment process based on the selected payment method.

  2. There should be an array of key-value pairs. Only string values are allowed.

  3. If not provided, all available payment methods will be allowed. Array should contain only supported payment methods short code.

Next, initiate the payment by calling our API with the collected payment details (don't forget to authorize with your secret key).

Example request :

POST /v1/payments/initialize
Host: https://api.moneroo.io
Authorization: Bearer YOUR_SECRET_KEY
Content-Type: application/json
Accept: application/json
{
    "amount": 100,
    "currency": "USD",
    "description": "Payment for order #123",
    "customer": {
        "email": "john@example.com",
        "first_name": "John",
        "last_name": "Doe"
    },
    "return_url": "https://example.com/payments/thank-you"
    "metadata": {
        "order_id": "123",
        "customer_id": "123" 
    },
    "methods": ["mtn_bj", "moov_bj"] //Once again, it not required
}

Example response :

{
  "message": "Transaction initialized successfully",
  "data": {
    "id": "5f7b1b2c",
    "checkout_url": "https://checkout.moneroo.io/5f7b1b2c"
  }
}

You only need to redirect your customer to the link returned in data.link. We will display our payment interface for the customer to make the payment.

Step 4: After Payment

Once the payment is made (successful or failed), four things will occur:

  • We redirect to your return_url with status, paymentId, and paymentStatus in the query parameters once the payment is completed.

  • We will send you a webhook if you have activated it. For more information on webhooks and to see examples, check out our webhooks guide.

  • We will send an acknowledgment email to your customer if the payment was successful (unless you have disabled this).

  • We will email you (unless you have disabled this).

  • On the server side, you need to handle the redirection and always check the final status of the transaction.

If you have webhooks enabled, we'll send you a notification for each failed payment attempt. This is useful in case you want to later reach out to customers who had issues paying. See our webhooks guide for an example.

Example

  • Please do not forget to replace YOUR_SECRET_KEY with your actual secret key.

  • All following examples should be made in backend, never expose your secret key to the public.

curl -X POST https://api.moneroo.io/v1/payments/initialize \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_SECRET_KEY" \
     -H "Accept: application/json" \
     -d '{
         "amount": 100,
         "currency": "USD",
         "description": "Payment for order #123",
         "customer": {
             "email": "john@example.com",
             "first_name": "John",
             "last_name": "Doe"
         },
         "return_url": "https://example.com/payments/thank-you",
         "metadata": {
             "order_id": "123",
             "customer_id": "123"
         },
         "methods": ["qr_ngn", "bank_transfer_ngn"]
     }'

Last updated