Yaspa's Guaranteed Payments product enables merchants to accept guaranteed pay-ins from consumer checking / savings accounts.

Integration follows the convention laid out in the Product Overview. Send Yaspa a pay-in instruction API call with the payment details and open the URL Yaspa returns to start the hosted pay-in journey. There, the customer grants Yaspa access to their account information. Yaspa then retrieves account, activity, and ownership information about each authorized account over open banking APIs, checks it against the customer information in your request to verify ownership, and applies fraud and risk rules. This culminates in a real-time payment approval backed by a guarantee.

At the end of the flow, Yaspa returns the customer to a configurable redirect URL and sends server-side webhook notifications at each status update. Accepted transactions are processed as debits over Same Day ACH and settle into a virtual account provisioned for the merchant. If Yaspa receives an eligible return (chargeback) for the transaction, Yaspa assumes liability for any losses and sends a webhook so you can flag the customer as high-risk and update controls accordingly.

Integration Guide

Create Hosted Pay-in API

When the customer selects Yaspa at checkout, use the Create Hosted Pay-in API to send Yaspa the information required to create a pay-in session as in the full example provided below:

curl --request POST \
  --url https://api.sandbox.us.yaspa.com/v2/payins/hosted-payin/generate-link \
  --header 'AuthorizationCitizen: {private API key}' \
  --header 'Accept: text/plain' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerIdentifier": "xekzyz3lorw9",
  "paymentGiro": "ACH",
  "amount": 10.01,
  "currency": "USD",
  "reference": "3pdcj42fpn9t",
  "journeyType": "INTELLIGENT_PAYMENT",
  "supportedCountries": ["US"],
  "successRedirectUrl": "http://www.example.com/success",
  "failureRedirectUrl": "http://www.example.com/failure",
  "customerDetails": {
    "firstName": "John",
    "lastName": "Smith",
    "email": "[email protected]",
    "dob": "1970-01-01",
    "mobile": "+15555555555",
    "address": {
      "address1": "123 Any Street",
      "address2": "Apt A",
      "city": "Boston",
      "stateCode": "MA",
      "zipCode": "02134",
      "countryCode": "US"
    }
  }
}
'

Upon receipt, Yaspa creates a transaction and maps it to a customer profile tied to the merchant. For customers paying the merchant with Yaspa for the first time, Yaspa creates a new customer tied to the the customerIdentifier paired with the customerDetails.email. The response is a link for the hosted pay-in session including a transaction identifier and a boolean to flag returning customers. Log the transaction-id value from the URL as this will be included in subsequent webhooks as the transactionId and can be used with the reference and customerIdentifier to tie the session and webhooks back to the your payment request and customer profile.

https://banks.sandbox.us.yaspa.com/hosted?transaction-id=d7941707-fe9f-fa8d-2491-3da414&secondTimeUser=false

Redirect Handler

Redirect the customer to the URL provided in the API response, paying particular attention to container version requirements in native mobile apps. When the customer completes the Yaspa journey, the hosted page redirects them to the success or failure URL, depending on the outcome. You can set these destinations as static values in the Admin Dashboard or at the transaction level using the successRedirectUrl and failureRedirectUrl parameters in the request. The per-transaction approach is strongly recommended because you can append data to the URLs. For example, use clearly distinct success and failure URLs and add the reference as a parameter to identify the result and session when the customer returns:

"successRedirectUrl": "https://www.example.com/success&ref={{ref}}",
"failureRedirectUrl": "https://www.example.com/failure&ref={{ref}}"

Webhooks

Yaspa sends webhooks for each status change throughout the customer journey and at milestones in the ensuing ACH processing. Release deposited funds or fulfill the goods or services ordered when the transaction is approved, as identified by the ACCEPTED status.

Webhooks for guaranteed payments follow the payment webhook version 3 structure and are sent as HTTPS POST requests. As noted above, several merchant-defined identifiers follow the transaction throughout its lifecycle so that it can be easily mapped to your payment stack. A typical example of the request body is as follows:

{
  "type": "PAYIN_DECISION",
  "data": {
    "id": "6ac021de351a3351401565cb",
    "transactionId": "d7941707-fe9f-fa8d-2491-3da414",
    "version": "3",
    "transactionType": "PAYIN",
    "transactionStatus": "ACCEPTED",
    "createdAt": "2026-10-02T21:27:58.510Z",
    "reference": "3pdcj42fpn9t",
    "language": "en",
    "merchant": {
      "id": "69bbee7367f8982c81665203",
      "tradingName": "example.com",
      "accountNumber": "cbe99239-943a-4ed7-98da-22da07e158b0",
      "bankCode": "cbe99239-943a-4ed7-98da-22da07e158b0"
    },
    "customer": {
      "identifier": "xekzyz3lorw9",
      "emailAddress": "[email protected]"
    },
    "account": {
      "identifier": "CHECKING",
      "financialInstitution": "US Test Bank",
      "holderName": "John Smith",
      "numberLastFour": "7890",
      "routingNumber": "222222226",
      "verificationTransactionId": "cd024f11-d382-24a2-35e8-87e7ae"
    },
    "payment": {
      "amount": "10.01",
      "currency": "USD",
      "giro": "ACH"
    },
    "journey": {
      "type": "INTELLIGENT_PAYMENT",
      "authType": "STANDARD",
      "verified": true,
      "enhanced": false
    }
  }
}

Type and Status Definitions

Status Model

Only failures are truly terminal. SETTLED is not terminal because returns may be filed after settlement and funds have been made available. If a transaction is returned, Yaspa marks it RETURNED so that you can flag the customer as high-risk and update your risk controls. If the return code is covered by the guarantee, the status advances to GUARANTEED, which is terminal and means Yaspa has assumed financial liability for the return and covered any losses in the virtual account.

Recommended Configuration

Configure the webhook endpoint and the enabled events in the Admin Dashboard. Not every event is mandatory, particularly intermediate statuses. At a minimum, Yaspa strongly recommends enabling ACCEPTED, SETTLED, RETURNED, and the terminal statuses, which together capture every failure mode and every status with risk or settlement implications:

Settlement and Reconciliation in the Admin Dashboard

Yaspa processes guaranteed pay-ins over Same Day ACH, with a 3pm Central Time final cutoff. Funds settle into the merchant's Virtual Account and are released into the Available Balance for withdrawal on T+2.

• A pay-in reaching ACCEPTED before 3pm CT on Monday is marked SETTLED and released into the Available Balance around 11am CT on Wednesday.
• A pay-in accepted after 3pm CT on Tuesday is available on Friday morning.
• Between acceptance and settlement, pay-ins count toward the Pending Balance shown beside the balance summary on the Admin Dashboard Ledger page.
• If a pay-in is returned and the return code is covered by the guarantee, Yaspa marks it GUARANTEED and releases funds on the normal schedule.

Finance users can withdraw from the Available Balance at any time with the Withdraw button on the Ledger page. Set an amount that maintains the required minimum balance and select a destination account. Withdrawals are processed as instant credits to the merchant business account, falling back to Same Day ACH if instant is unavailable or unsupported by the bank holding the account. The Ledger page also provides detailed balance activity reporting (pay-ins, payouts, top-ups and withdrawals), which can be filtered and exported as CSV for reconciliation.

First Time Customer Sequence Diagram

The following diagram shows the complete integration flow from initiation to full approval. Settlement, reconciliation, and failure conditions are excluded for clarity.

Returning Customer Sequence Diagram

Returning customers with bank accounts in good standing enjoy a streamlined user experience. Upon redirection to the Yaspa hosted payment page, returning customers will be able to select from accounts on file to complete payment. To configure the hosted payment page for a returning customer, provide an established customerIdentifier with the corresponding customerDetails.email in the request body, as Yaspa uses the former to create the saved account and validates that the latter matches that on file with the saved account. Otherwise, the integration is essentially the same as the first time customer flow.

Failure Handling

The hosted journey shows clear messages so that customers can resolve soft declines in-session and understand a failure before being redirected back. While it is not necessary to establish your own messaging for each possible scenario, failure handling may be configured based on the following transaction status and error details provided via webhook notification.