TodayPay Docs
  • TodayPay Platform
    • Overview
    • Environments
    • Authentication and connection
    • Payments Overview
    • Initiating Payments via Batch File
      • SFTP File Submission
      • API File Submission
    • Initiating Payments via API
    • Notifying customers
    • Reporting
      • Payment Report File
  • API Reference
    • Payments API
  • Guides
    • Initiating Multiple Payments to Same Customer
    • Sending Payments from the Dashboard
Powered by GitBook
On this page
  1. API Reference

Payments API

PreviousPayment Report FileNextInitiating Multiple Payments to Same Customer

Last updated 3 days ago

Payment Cancellation

Payments an be canceled as long as the customer has not logged in and claimed the payment. Cancellation requests will fail if a payment is not eligible for Cancellation.

Replace a payment with amended details

Payments an be amendment as long as the customer has not logged in and claimed the payment. Amend requests will fail if a payment is not eligible for cancelation.

Cancel Payment

delete

Cancels a specific payment.

Authorizations
Path parameters
payment_idstringRequiredExample: txn_Zz6xMSJsokwq
Responses
200
Payment successfully canceled
application/json
400
Payment not eligible for cancelation
401
Unauthorized
404
Payment not found
delete
DELETE /v1/payments/{payment_id} HTTP/1.1
Host: api-sandbox.todaypay.me
Authorization: Basic username:password
Accept: */*

{
  "status": "success",
  "message": "Payment canceled"
}
  • GETGet info and status of payment.
  • POSTInitiate paper check fallback.
  • Payment Cancellation
  • DELETECancel Payment
  • Replace a payment with amended details
  • POSTReplace payment with ammended details.

Get info and status of payment.

get

Retrieves the info status of a specific payment.

Authorizations
Path parameters
payment_idstringRequiredExample: txn_Zz6xMSJsokwq
Responses
200
Successful response with payment info
application/json
401
Unauthorized
404
Payment not found
get
GET /v1/payments/{payment_id} HTTP/1.1
Host: api-sandbox.todaypay.me
Authorization: Basic username:password
Accept: */*

{
  "status": "success",
  "data": {
    "id": "txn_Zz6xMSJsokwq",
    "amount": "1000.00",
    "status": "SUCCESS",
    "method": "DIGITAL",
    "cancellable": true,
    "phone_number": "+1234567890",
    "first_name": "John",
    "last_name": "Doe",
    "email": "user@example.com",
    "mailing_address": {
      "line_1": "165 W Broadway",
      "line_2": "Apt 5",
      "state": "NY",
      "city": "New York",
      "zip": "10005"
    },
    "idempotency_key": "abc123-unique-key",
    "datetime_initiated": "2025-03-12T14Z",
    "notes": "003993849393",
    "claimed": true,
    "datetime_claimed": "2025-05-12T14Z",
    "claim_metadta": {
      "ip_address": "192.168.1.1",
      "device_id": "92dOtZmtCuWlZ6nryeZU2iX7TmZPguoB"
    }
  }
}

Initiate paper check fallback.

post

Cancels digital payment and creates new paper check payment. The new payment retains the notes and idepmpotency key of the old payment. First name, last name, and address must be re-specified on the request, even if included on the original payment. This request will fail if the orignal payment can't be canceled. The final result of a the operation is 1) orignal payment cancled and 2) a new paper-check payment is generated under a new payment id.

Authorizations
Path parameters
payment_idstringRequiredExample: txn_Zz6xMSJsokwq
Body
first_namestringRequiredExample: John
last_namestringRequiredExample: Smith
Responses
200
Successful response with new payment id.
application/json
400
Payment not eligible for fallback. This will occur if the original a payment is not eleigible for cancelation.
401
Unauthorized
404
Payment not found
post
POST /v1/payments/{payment_id}/fallback HTTP/1.1
Host: api-sandbox.todaypay.me
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 149

{
  "first_name": "John",
  "last_name": "Smith",
  "mailing_address": {
    "line_1": "160 W Broadway",
    "line_2": "Apt 5",
    "state": "NY",
    "city": "New York",
    "zip": "10005"
  }
}
{
  "status": "success",
  "data": {
    "old_payment_id": "txn_Zz6xMSJsokwq",
    "new_payment_id": "txn_a035g4h567ga"
  }
}

Replace payment with ammended details.

post

Cancels digital payment and creates new digital payment with updates details. The new payment retains the notes and idepmpotency key of the old payment. Email, phone, first_name, and last_name must be re-specified. Amount can't be amended.

Authorizations
Path parameters
payment_idstringRequiredExample: txn_Zz6xMSJsokwq
Body
first_namestringRequired

The name of the user

Example: John
last_namestringRequiredExample: Smith
emailstring | nullableOptionalExample: user@example.com
phone_numberstring | nullableOptionalExample: +1234567890
Responses
200
Successful response with new payment id.
application/json
400
Payment not eligible for amendment. This will occur if the original payment is not eleigible for cancelation.
401
Unauthorized
404
Payment not found
post
POST /v1/payments/{payment_id}/amend HTTP/1.1
Host: api-sandbox.todaypay.me
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 205

{
  "first_name": "John",
  "last_name": "Smith",
  "email": "user@example.com",
  "phone_number": "+1234567890",
  "mailing_address": {
    "line_1": "160 W Broadway",
    "line_2": "Apt 5",
    "state": "NY",
    "city": "New York",
    "zip": "10005"
  }
}
{
  "status": "success",
  "data": {
    "old_payment_id": "txn_Zz6xMSJsokwq",
    "new_payment_id": "txn_a035g4h567ga"
  }
}