Payment Confirmation

Overview

The Payment Confirmation API closes the payment loop between your ERP and SoftCo. When your accounts payable team processes a payment run in your ERP, the invoices are settled on your side — but SoftCo still shows them as outstanding until it receives confirmation. Sending a confirmation record to this endpoint updates the matching invoice in SoftCo to reflect its paid status, keeping both systems in sync and preventing duplicate payment processing.

A single call to POST /payment-confirmation/v1 confirms one or more invoice payments. Each record provides SoftCo's internal case ID for the invoice, your ERP's voucher number, the payment reference from your payment run, and the date the payment was processed. SoftCo matches on softco_case_id and updates the invoice record accordingly.

How payment confirmation fits into the AP cycle

SoftCo raises and processes invoices on the AP side. When your ERP is used for payment execution — rather than SoftCo's own payment module — SoftCo needs to be told about each payment after the fact. This API is that notification channel. It is not a payment instruction: it is a confirmation that payment has already been made.

When to call this endpoint

Quick Start

Here's the fastest path to a successful integration. Copy this request, swap in your credentials and a real invoice reference, then send it. All four fields are required — softco_case_id, voucher_number, payment_number, and payment_date.

POST /payment-confirmation/v1
x-api-key:     your-api-key-here
Content-Type:  application/Json
Client_Id:     your-client-id
Client_Secret: your-client-secret

{
  "objects": {
    "object": {
      "record": [
        {      
        "softco_case_id":   "10045123",
        "voucher_number":   "PAY-20240315-001",
        "payment_number":   "5832",
        "payment_date":     "2024-03-15"
        }
      ]
    }
  }
}

A successful response looks like this:

{
  "status":    "SUCCESS",
  "total":     1,
  "succeeded": 1,
  "failed":    0,
  "errors":    [],
  "message":   "All items processed successfully"
}

How It Works

Every request follows the same pipeline. Your system only needs to send once — validation, transformation, and delivery to SoftCo are handled automatically.

Authentication

All requests require an API key and OAuth 2.0 credentials. Your credentials are provided during onboarding — keep them secure and never expose them in client-side code or version control.

Requests with a missing or invalid API key are rejected by the gateway immediately and never reach the integration layer.

Required Headers

Response Codes

POST /payment-confirmation/v1

Submit one or more payment confirmation records to SoftCo. Each record matches an invoice by its softco_case_id and updates it to reflect the payment made in your ERP. The payload is validated and queued for delivery to SoftCo.

Request Headers

Request Body

The request body uses the same objects → object → record envelope as all SoftCo iPaaS APIs. For a single payment confirmation, record is a JSON object. For multiple confirmations in one request, record is a JSON array of objects.

Single record

Batch (multiple confirmations)

Field Reference

The Payment Confirmation API has a compact field set — exactly four fields, all required. All four values are passed directly to SoftCo without transformation — what you send is exactly what SoftCo receives.

Example Requests

Single payment confirmation

POST /payment-confirmation/v1
x-api-key:     your-api-key-here
Content-Type:  application/Json
Client_Id:     your-client-id
Client_Secret: your-client-secret

{
  "objects": {
    "object": {
      "record": [
        {      
        "softco_case_id":   "10045123",
        "voucher_number":   "PAY-20240315-001",
        "payment_number":   "5832",
        "payment_date":     "2024-03-15"
        }
      ]
    }
  }
}

Batch — multiple confirmations in one request

POST /payment-confirmation/v1
x-api-key:     your-api-key-here
Content-Type:  application/Json
Client_Id:     your-client-id
Client_Secret: your-client-secret

{
  "objects": {
    "object": {
      "record": [
        {
          "softco_case_id":   "10045123",
          "voucher_number":   "PAY-20240315-001",
          "payment_number":   "5832",
          "payment_date":     "2024-03-15"
        },
        {
          "softco_case_id":   "10045124",
          "voucher_number":   "PAY-20240315-002",
          "payment_number":   "5833",
          "payment_date":     "2024-03-15"
        },
        {
          "softco_case_id":   "10044891",
          "voucher_number":   "PAY-20240315-003",
          "payment_number":   "5834",
          "payment_date":     "2024-03-15"
        }
      ]
    }
  }
}

Validation

Every request is validated before any processing takes place. If validation fails, the request is rejected immediately and nothing is queued or forwarded to SoftCo — you receive a clear error identifying the problem field.

What is checked

Validation error response

When validation fails, the API returns a 400 Bad Request with a JSON body identifying the failing field:

{
  "status":    "FAILED",
  "total":     0,
  "succeeded": 0,
  "failed":    0,
  "errors":    [
    {
      "index": 0,
      "error": "required key [payment_date] not found"
    }
  ],
  "message":   "No items could be processed as the request structure was invalid."
}

The errors array identifies the exact field that failed. Fix the identified field and resubmit.

Troubleshooting

The four common error scenarios and how to resolve them.

Example Responses

202 Accepted — All Records Processed

Every record in the request was validated and queued successfully. Delivery to SoftCo is asynchronous and typically completes within minutes.

{
  "status":    "SUCCESS",
  "total":     1,
  "succeeded": 1,
  "failed":    0,
  "errors":    [],
  "message":   "All items processed successfully"
}

207 Multi-Status — Partial Success

Some records were queued; one or more failed validation. Only the failed records need to be fixed and resubmitted.

{
  "status":    "PARTIAL",
  "total":     2,
  "succeeded": 1,
  "failed":    1,
  "errors":    [
    {
      "index": 2,
      "error": "required key [payment_date] not found"
    }
  ],
  "message":   "Your request was partially successful. 1 of 2 records were queued for delivery."
}

400 Bad Request — Invalid Request Structure

The request envelope is missing or malformed. No records were processed.

{
  "status":           "FAILED",
  "total":            0,
  "succeeded":        0,
  "failed":           0,
  "errors":           [
    {
      "index": 0,
      "error": "The request is missing the objects section."
    }
  ],
  "message":          "No items could be processed as the request structure was invalid.",
  "expected_format":  "objects → object → record (record must be a non-empty array of items)"
}

401 Unauthorized

API key missing or invalid. Request rejected at the gateway before reaching the integration layer.

{
  "status":    "FAILED",
  "message":   "Unauthorized — API key is missing or invalid"
}

What's Next

Payment Confirmation completes the transactional feedback loop. The remaining transaction data APIs cover the purchase-to-pay cycle on the inbound side.

Transaction Data APIs

Master Data APIs