Payment Submission

A Payment Submission in the Paylias network represents the actual processing request for a payment. It tracks the lifecycle of a payment as it moves through the network and contains the processing status and related payment details.

Overview

Each Payment Submission:

Links to a specific Payment record
Tracks the processing status
Contains submission timing information
Includes relationships to related resources
Provides status reasoning when applicable

Payment Submission Resource

Property	Type	Required	Description	Notes
`token`	string	Yes	Unique identifier for the submission	Auto-generated
`payment_id`	string	Yes	ID of the associated payment	Must exist
`organization_id`	string	Yes	Organization initiating the submission	Auto-populated from auth
`partner_id`	string	Yes	Partner under organization	Auto-populated from auth
`status`	enum	Yes	Current processing status	See Status Values
`status_reason`	string	No	Description of current status	Optional context
`submission_time`	int64	Yes	Processing start timestamp	Unix timestamp
`relationships`	object	No	Related resources	See Relationships Properties

Status Values

Value	Description
`Submission_None`	Initial state, not yet processed
`Submission_Accepted`	Accepted and pending processing
`Submission_DeliveryConfirmed`	Received and accepted by counterparty
`Submission_DeliveryFailed`	Rejected by Paylias or counterparty
`Submission_ValidationPending`	Awaiting Paylias validation

Relationships Properties

Property	Type	Required	Description
`payment`	object	No	Complete payment record details

Payment Submission Record Type

{
    "ok": true,
    "data": {
        "token": "sub_cvk3jvs20or8munut3l0",
        "payment_id": "cjes76vsemvj3obsnc52",
        "organization_id": "org_ct239n420or249k5bo90",
        "partner_id": "part_ct23b6420or249k5boag",
        "status": 2,
        "submission_time": 1743272447,
        "relationships": {
            "payment": {
                "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 Submission

Submits a payment for processing across the network.

Required Headers

Header	Description
`X-Org-ID`	Organization identifier
`X-Partner-ID`	Partner identifier
`X-Sfpy-Api-Key`	API key for authentication

Path Parameters

Parameter	Type	Required	Description
`paymentId`	string	Yes	ID of payment to submit

`POST /api/v1/csp/payments/{paymentId}/submissions`

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

Find Payment Submission

Retrieves details of a specific payment submission.

Required Headers

Header	Description
`X-Org-ID`	Organization identifier
`X-Partner-ID`	Partner identifier
`X-Sfpy-Api-Key`	API key for authentication

Path Parameters

Parameter	Type	Required	Description
`paymentId`	string	Yes	ID of the payment
`submissionId`	string	Yes	ID of the submission

`GET /api/v1/csp/payments/{paymentId}/submissions/{submissionId}`

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

Error Codes

Error Code	Description
`error.bad_request`	Invalid or missing required parameters
`error.resource_not_found`	Payment or submission not found
`error.unauthorized_access`	Invalid or missing authentication
`error.resource_conflict`	Payment submission already exists