Payment

A Payment in the Paylias network represents a transaction between two parties. It contains detailed information about the transaction participants, amounts, and contextual data to facilitate secure money movement.

Overview

Each Payment:

• Has unique identifiers across organizations
• Contains detailed information about transaction parties
• Includes amount and currency details
• Supports device and location tracking for security
• Has built-in expiration handling

Payment Creation vs Submission

When creating a payment through the /api/v1/csp/payments endpoint, it's important to understand that this only stores the payment record and performs basic validations such as:

• Authentication and authorization checks
• Payment ID uniqueness verification
• Required field presence and format validation

The payment is not automatically submitted to the network for processing.

To actually process the payment through the Paylias network, you must make a separate call to the Submit Payment endpoint. This endpoint performs deep validation checks and initiates the actual payment processing. Please refer to the Submit Payment API documentation for details on this process.

Payment Resource

Amount Properties

Entity Properties

Billing Properties

Metadata Properties

Device Properties

Location Properties

Payment Record Type

{
    "ok": true,
    "data": {
        "payment_id": "cjes76vsemvj3obsnc52",
        "organization_id": "org_ct239n420or249k5bo90",
        "partner_id": "part_ct23b6420or249k5boag",
        "reference": "INV0001",
        "initiated_at": 1743270060,
        "expires_at": 1743273661,
        "amount": {
            "currency": "USD",
            "total": "10000"
        },
        "debtor_party": {
            "payment_address": "john@stripe-platinum",
            "first_name": "John",
            "last_name": "Collison",
            "email": "johnc@stripe.com",
            "phone": "+16462442945",
            "type": "Payee_Individual",
            "billing": {
                "country": "US"
            }
        },
        "beneficiary_party": {
            "payment_address": "ziyad@safepay-platinum",
            "first_name": "Ziyad",
            "last_name": "Parekh",
            "email": "ziyad.parekh@gmail.com",
            "phone": "+923008277879",
            "type": "Payee_Individual",
            "billing": {
                "country": "US"
            }
        },
        "device": {},
        "location": {}
    }
}

API Endpoints

Create Payment

Creates a new payment transaction.

Required Headers

POST /api/v1/csp/payments

curl --location 'http://localhost:9001/api/v1/csp/payments' \
--header 'X-Org-ID: org_ct239n420or249k5bo90' \
--header 'X-Partner-ID: part_ct23b6420or249k5boag' \
--header 'Content-Type: application/json' \
--header 'X-Sfpy-Api-Key: AA5B7256D7E228329F9A7D6E58880D48' \
--data '{
    "payment_id": "cjes76vsemvj3obsnc52",
    "reference": "INV0001",
    "initiated_at": 1743270454,
    "amount": {
        "currency": "USD",
        "total": "10000"
    },
    "beneficiary_party": {
        "payment_address": "ziyad@safepay-platinum",
        "first_name": "Ziyad",
        "last_name": "Parekh",
        "email": "ziyad.parekh@gmail.com",
        "phone": "+923008277879",
        "type": "Payee_Individual",
        "billing": {
            "street_1": "",
            "country": "US"
        }
    },
    "debtor_party": {
        "payment_address": "john@stripe-platinum",
        "first_name": "John",
        "last_name": "Collison",
        "email": "johnc@stripe.com",
        "phone": "+16462442945",
        "type": "Payee_Individual",
        "billing": {
            "street_1": "",
            "country": "US"
        }
    }
}'

Find Payment

Retrieves details of a specific payment.

Path Parameters

Required Headers

GET /api/v1/csp/payments/{paymentId}

curl --location 'http://localhost:9001/api/v1/csp/payments/cjes76vsemvj3obsnc53' \
--header 'X-Org-ID: org_ct239n420or249k5bo90' \
--header 'X-Partner-ID: part_ct23b6420or249k5boag' \
--header 'X-Sfpy-Api-Key: AA5B7256D7E228329F9A7D6E58880D48'

Error Codes

Validation Rules

1. Timestamps

   • initiated_at must not be in the future
   • expires_at must be after initiated_at
   • expires_at must not be expired

2. Amount

   • Currency must be valid ISO 4217 code
   • Amount must be positive
   • Amount must be numeric

3. Entities

   • Payment addresses must be valid format
   • Email addresses must be valid format
   • Phone numbers must include country code
   • Business entities must include category code

4. Metadata

   • Maximum 5 key-value pairs
   • Keys and values limited to 45 characters

5. Billing

   • Country must be valid ISO 3166 code
   • All string fields must not exceed maximum lengths
   • Country is the only required field

6. Metadata

   • Both key and value must be alphanumeric
   • Both key and value must not exceed 45 characters
   • Maximum of 5 metadata entries per payment

7. Device

   • User agent must be valid format if provided
   • User agent must not exceed 500 characters
   • Boolean fields default to false if not provided

8. Location

   • IP address must be valid IPv4/IPv6 format if provided
   • Latitude and longitude must be valid geographic coordinates
   • All location fields are optional but must be valid if provided

Best Practices

1. Billing Information

   • Always provide as much billing information as available
   • Ensure country codes are uppercase
   • Validate addresses when possible

2. Metadata Usage

   • Use consistent key naming conventions
   • Keep values concise and meaningful
   • Don't store sensitive information in metadata

3. Device Information

   • Always send user agent when available
   • Include mobile/crawler flags for better tracking
   • Keep device information current

4. Location Data

   • Respect privacy laws when collecting location data
   • Validate IP addresses before sending
   • Use standardized formats for geographic coordinates