Create a payin

To pull funds from a connected payment instrument, send a request to POST /v3/profiles/{{profileId}}/payment-instruments/{{paymentInstrumentId}}/payins.

You must provide the payinSessionId, which links the payment to a specific transfer you are funding.

The API returns a payin object with a status of PROCESSING.

Sample request:

POST /v3/profiles/{{profileId}}/payment-instruments/{{paymentInstrumentId}}/payins

{
  "payinSessionId": "8d63a219-eb86-42c7-a785-02875c281507",
  "reference": "PAY0001"
}

Sample response:

201
{
  "id": "123",
  "amount": "10.00",
  "currency": "GBP",
  "status": "PROCESSING" | "CONFIRMED" | "SETTLED" | "FAILED",
  "paymentInstrumentId": "fabfcf6e-3ac3-4d5f-ac96-340b71e6be9e",
  "payinSessionId": "8d63a219-eb86-42c7-a785-02875c281507",
  "reference": "PAY0001",
  "failureReason": "null"
}

You can monitor the status of a Payin to see its progression. Send a GET request to the relevant endpoints to retrieve its status.

Sample request:

GET /v3/profiles/{{profileId}}/payment-instruments/{{paymentInstrumentId}}/payins/{{paymentId}}

GET /v3/profiles/{{profileId}}/payment-instruments/{{paymentInstrumentId}}/payins

Sample response:

200
{
  "id": "123",
  "amount": "10.00",
  "currency": "GBP",
  "status": "PROCESSING" | "CONFIRMED" | "SETTLED" | "FAILED",
  "paymentInstrumentId": "fabfcf6e-3ac3-4d5f-ac96-340b71e6be9e",
  "payinSessionId": "8d63a219-eb86-42c7-a785-02875c281507",
  "reference": "PAY0001",
  "failureReason": "REFER_TO_PAYER" | "INSTRUMENT_CLOSED_AT_SOURCE" | "INVALID_INSTRUMENT_DETAILS" | "INSTRUMENT_AUTHORISATION_TRANSFERRED" | "INSTRUMENT_AUTHORISATION_DISPUTED" | "INSTRUMENT_DISCONNECTED" | "PAYIN_TYPE_NOT_ENABLED" | "OTHER" | null
}

Payments can fail for various reasons. You must handle these scenarios gracefully.

• Failed Payin: If a Payin fails, the status is FAILED. The failureReason field provides details, such as INSUFFICIENT_FUNDS or INVALID_INSTRUMENT_DETAILS. You should communicate this reason to your customer. You can retry the payment by creating a new Payin.
• Disconnected Instrument: A Payment Instrument can become DISCONNECTED if the customer cancels their authorization or for other reasons. The disconnectionReason provides details. You cannot use a disconnected instrument for payments. To recover, you must have the customer re-authorize the instrument and then manually confirm it again by sending a request to the POST endpoint.