Payment API Documentation

Prerequisites for Merchants

Merchant Account Creation

Before being able to accept payments, merchants must:

1. Account Creation
   • Register on the platform
   • Provide basic business information
   • Accept the terms of use
2. Payment Information Setup
   • Configure withdrawal methods:
     • Mobile Money
     • Bank account
   • Verify and validate banking details
3. KYB Process (Know Your Business)
   • Business identity verification
   • Submission of official documents
   • Validation by the compliance team

Environments

1. Production environment

   https://api.elyonpay.org/api

2. Test environment

   https://api.elyonpay.net/api

To make requests in the test environment, you need to use the following user to log in:

{
  "username": "test@test.com",
  "password": "TestPassword1",
  "role": "ROLE_CUSTOMER"
}

Authentication

Login Endpoint

Endpoint

POST /api/login

Description

Authenticate and receive a JSON Web Token (JWT) to access protected endpoints.

Request Headers

Request Body

Request Example

curl --location 'http://localhost:8000/api/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "jhon.doe@user.com",
    "password": "ThisIsMyPassword1234",
    "role": "ROLE_MERCHANT_ADMIN"
}'

Success Response

Status Code: 200 OK

Success Response Example

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...."
}

Error Responses

Token Details

The returned JWT token contains:

• iat (Issued At: Token creation timestamp): Issued At: Token creation timestamp
• exp (Expiration: Token expiration timestamp): Expiration: Token expiration timestamp
• roles: Array of user roles
• phoneNumber: Phone number associated with the user

Usage Instructions

1. Send a login request with the correct credentials
2. Receive the JWT token
3. Include the token in the Authorization header for protected endpoints
   • Authorization: Bearer <token>

Security Recommendations

• Store the token securely on the client side
• Implement a token refresh mechanism
• Check token expiration before making requests
• Never share your token publicly

Payment Link

Endpoint

POST /api/request-to-pay/payment/link

Description

This endpoint generates a payment transaction link that can be opened in a new page or in an iframe.

Request Headers

Request Body

Request Example

curl --location 'http://localhost:8000/api/request-to-pay/payment/link' \
--header 'language: en' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE3NDMwMDU2NjgsImV4cCI6MTc0MzE4NTY2OCwicm9sZXMiOlsiUk9MRV9D...' \
--data '{
    "amount": 1.00,
    "user_lang": "en",
    "msisdn": "+22507377932",
    "success": "https://www.success.com",
    "error": "https://www.error.com"
}'

Success Response

Status Code: 200 OK

Success Response Example

{
  "url": "http://app.elyonpay.org/t/CI032667e43abf11?success=https://www.success.com&error=https://www.error.com"
}

Error Responses

Payment Integration Flow

Flow Diagram

sequenceDiagram
  participant Customer
  participant Merchant
  participant ElyonPay

  Customer->>Merchant: Finalizes cart
  Customer->>Merchant: Selects "Pay"
  Merchant->>ElyonPay: POST /api/login
  ElyonPay-->>Merchant: Returns JWT token
  Merchant->>ElyonPay: POST /api/request-to-pay/payment/link
  ElyonPay-->>Merchant: Returns payment URL
  Merchant->>Customer: Displays payment page (iframe or redirect)
  Customer->>ElyonPay: Selects payment method
  Customer->>ElyonPay: Completes transaction
  ElyonPay-->>Customer: Shows confirmation popup
      

Detailed Steps

1. On the Merchant Website
   • Customer finalizes their cart
   • Selects "Pay"
2. Merchant Server Side
   • Call the /api/login endpoint /api/login
   • Obtain a JWT token
3. Payment Link Generation
   • Call POST /api/request-to-pay/payment/link POST /api/request-to-pay/payment/link
   • Receive a link with unique ID (e.g., CM0130679b857c09)
4. Payment Display
   • Integration in an iframe
   • Or opening in a new page
5. Payment Process
   • Customer selects a payment method
   • Completes the transaction
   • Confirmation popup at the end of the payment

Payment Result Handling

sequenceDiagram
  participant Customer
  participant Merchant
  participant ElyonPay

  Customer->>ElyonPay: Transaction completed
  alt Successful payment
      ElyonPay->>Merchant: Redirect to success URL
  else Failed payment
      ElyonPay->>Merchant: Redirect to error URL
  end
  Merchant->>ElyonPay: GET /api/transactions/[ID_TRANSACTION]
  ElyonPay-->>Merchant: Returns transaction status
  Merchant->>Merchant: Updates order status
  Merchant->>Customer: Shows order confirmation
      

6. Redirections
   • Success URL in case of successful payment
   • Error URL in case of a problem
   • Important: Must be a server-side URL
7. Final Verification
   • Call GET /api/transactions/[ID_TRANSACTION] GET /api/transactions/[ID_TRANSACTION]
   • Retrieve the final status
   • Update the order status

Transaction States

List of States

State Transition Diagram

stateDiagram-v2
  [*] --> CREATED
  CREATED --> PENDING: Payment initiated
  PENDING --> WAITING_FOR_PAYMENT: Awaiting customer
  WAITING_FOR_PAYMENT --> ACCEPTED: Payment confirmed
  PENDING --> ACCEPTED: Direct approval
  PENDING --> REJECTED: Validation failed
  PENDING --> DECLINED: Payment issue
  WAITING_FOR_PAYMENT --> DECLINED: Payment issue
  WAITING_FOR_PAYMENT --> CANCELLED: User cancellation
  ACCEPTED --> DELIVERED: Funds transferred
  ACCEPTED --> CANCELLED: Administrative action
  REJECTED --> [*]
  DECLINED --> [*]
  CANCELLED --> [*]
  DELIVERED --> [*]
      

Best Practices

Security

• Always use HTTPS
• Protect the JWT token
• Verify status on the server side
• Never rely solely on client redirection

Error Handling

• Implement retry mechanisms
• Handle timeout cases
• Provide clear messages to the user

Technical Recommendations

• Recommended timeout: 30 seconds
• Check status immediately after redirection
• Implement a verification queue

Error Codes

Authentication Errors

Transaction Errors

Support

In case of problems:

• Check the documentation
• Consult the logs
• Contact technical support