Skip to main content
API docs by Redocly

Payment Provider Webhooks (0)

Download OpenAPI specification:Download

Represents an entity that represents a source of funds. Use a financial instrument to capture, refund, or revoke money (or money equivalents).

Implement the methods of this resource to integrate with a PSP (payment service provider). PCI compliance is handled by the PSP.

For more information about the terminology, the integration procedure and use cases, see Integrating a payment service provider in our documentation.

Important: All these requests contain an idempotency key. Ensure that you send the same response every time you receive a request with a given idempotency key. For example, if you receive 3 requests containing the idempotency key abcd, whether the request body has changed or not, you must give the same response to these 3 requests.

See the following table for a list of error codes and their descriptions, which can appear during integration with the PSP:

Error code Description
internal_error An unexpected error that cannot be recovered from.
retry_error The client needs to retry the current request.
instrument_error An error specific to the financial instrument and the issuer. For example, "card declined".
fraud_error An error caused by fraudulent activity. When this error occurs, the PSP voids the instrument.
rate_limit Used to signal that the requests are too frequent.
failed_command The PSP cannot handle the command.

Note: The defined baseUri is for illustration purposes only. Edit it as needed.

Authenticating webhook requests

In order to authenticate the requests NewStore sends to the payment provider it is possible to configure an api_key for each provider.

To achieve this add the api_key field to the external provider in the fat_psp configuration. See FAT PSP configuration

Create financial instrument

Creates a financial instrument and reserves funds.

A financial instrument is created from some form of tokenized fund source, depending on the underlying payment provider, and it is initialized with a specific amount.

The instrument to create is originally defined by NewStore via a request to the considered PSP. For example, NewStore can receive a gift card number from the customer during checkout.

If supported, when a financial instrument is created, the initial monetary amount on the instrument is blocked until the instrument is captured fully or revoked (voided).

An instrument can be created by three possible provider-specific types of identifiers:

  • Token: A tokenized form of a payment source. The identifier is a token that can be used by the PSP to resolve to the source.
  • Authorized: A pre-authorized payment source. The identifier is a reference to the authorization. For example, an Adyen psp reference.
  • Captured: An already captured payment source. The identifier is a reference to the capture. For example, a transaction reference.

Note: When creating a financial instrument, the available-for-refund amount can be non-zero, for example in the case of pre-captured instruments.

The response returns the initial transaction(s) that sets the available-for-capture and available-for-refund amounts and the identifier (instrument_id) of the instrument generated by the PSP.

Note: Two financial instruments must not have the same ID. Keep this in mind when creating tests with a mock server that might send the same ID several time.

Request Body schema: application/json
account_id
required
string

The payment account identifier that holds the financial instrument.

idempotency_key
required
string

The request's idempotency identifier and correlation id. This field will be unique for each operation request, but will be the same for retries. The deal with always unique fields, use the retry_id instead.

retry_id
required
string

The request's unique id. This can be used as an idempotency key, as it will be unique even for retries of a single operation.

required
object

The arguments of the create operation. They describe the financial instrument to create.

metadata
object

Extra information related to this instrument and its payment account. As an integrator, get in touch with your contact point at NewStore to define the metadata you require. To display payment details in NOM and the Associate App, you will need to provide metadata->essential->instrument_metadata, in which you can add descriptions for Credit Card and Gift Card payments. For Credit Card payments, card_last4 and card_brand are used to display a description like 'Visa (**** 4312)'. For Gift Card payments, gift_card_number should be used instead of card_last4 to display a description string like 'Card number: (**** 6789)'

Responses

Request samples

Content type
application/json
{
  • "account_id": "9c849222-3bca-4881-9c68-2e91da34ab21",
  • "idempotency_key": "authorized.987600036172980-9c849222-3bca-4881-9c68-2e91da34ab21",
  • "arguments": {
    },
  • "metadata": { }
}

Response samples

Content type
application/json

In the following example, note the following information:

  • The instrument_id is unique across all identifier of payment and repeat itself for every new transaction done with this instrument. The transaction_id is unique for every transaction in this payload.
  • We are authorizing an instrument so we set the capture amount to a non-zero value and the refund amount to 0 since an authorized instrument cannot be refunded.
  • The metadata field shows the special essential > instrument_metadata object and its fields. This object is automatically processed.
    • For Credit Card payments, card_last4 and card_brand are used to display a description like "Visa (**** 4312)".
    • For Gift Card payments, gift_card_number should be used instead of card_last4 to display a description string like "Card number: (**** 6789)" Any other object in the metadata field, or any other fields are ignored by NOM.
[
  • {
    }
]

Capture funds

Captures the funds and transfers them from a customer to your business.

A transaction is returned that decreases the available-for-capture amount and optionally increases the available-for-refund amount, if the provider supports it.

A financial instrument supports multiple capture operations up until available-for-capture gets to zero.

If a capture operation results in an increase in the available-for-refund amount, the convention is to return it in the same transaction.

path Parameters
financial_instrument_id
required
string (financial instrument identifier)

The financial instrument identifier returned by the creation request above (instrument_id property).

Request Body schema: application/json
account_id
required
string

The payment account identifier that holds the financial instrument.

instrument_id
string or null

The integrator-owned identifier of the financial instrument that the operation will modify.

required
Array of objects (A financial instrument transaction)

The set of transactions describing the current state of the instrument. The transactions in this array are in no particular order.

idempotency_key
required
string

The request's idempotency identifier and correlation id. This field will be unique for each operation request, but will be the same for retries. The deal with always unique fields, use the retry_id instead.

retry_id
string

The request's unique id. This can be used as an idempotency key, as it will be unique even for retries of a single operation.

required
object

The arguments of the capture/refund operation. In the case of a revoke, these arguments are not provided and the amount and currency are those of the instrument.

metadata
object

Extra information related to this instrument and its payment account. For gift cards, the field 'original_operation' = 'refund' will always be provided. As an integrator, get in touch with your contact point at NewStore to define the metadata you require.

Responses

Request samples

Content type
application/json
{
  • "account_id": "af8e9f4a-b6ec-4677-a9a0-1ff199a8b2ef",
  • "instrument_id": "unique-psp-instrument-identifier-1234567890",
  • "transactions": [
    ],
  • "idempotency_key": "373fa237-d70e-4177-8139-41354a21c356",
  • "arguments": {
    },
  • "metadata": { }
}

Response samples

Content type
application/json
[
  • {
    }
]

Refund amount

Transfers a monetary amount from the business to the customer.

A transaction is returned that decreases the available-for-refund amount for the specific instrument.

A financial instrument supports multiple refund operations up until available-for-refund gets to zero.

path Parameters
financial_instrument_id
required
string (financial instrument identifier)

The financial instrument identifier returned by the creation request above (instrument_id property).

Request Body schema: application/json
account_id
required
string

The payment account identifier that holds the financial instrument.

instrument_id
string or null

The integrator-owned identifier of the financial instrument that the operation will modify.

required
Array of objects (A financial instrument transaction)

The set of transactions describing the current state of the instrument. The transactions in this array are in no particular order.

idempotency_key
required
string

The request's idempotency identifier and correlation id. This field will be unique for each operation request, but will be the same for retries. The deal with always unique fields, use the retry_id instead.

retry_id
string

The request's unique id. This can be used as an idempotency key, as it will be unique even for retries of a single operation.

required
object

The arguments of the capture/refund operation. In the case of a revoke, these arguments are not provided and the amount and currency are those of the instrument.

metadata
object

Extra information related to this instrument and its payment account. For gift cards, the field 'original_operation' = 'refund' will always be provided. As an integrator, get in touch with your contact point at NewStore to define the metadata you require.

Responses

Request samples

Content type
application/json
{
  • "account_id": "af8e9f4a-b6ec-4677-a9a0-1ff199a8b2ef",
  • "instrument_id": "unique-psp-instrument-identifier-1234567890",
  • "transactions": [
    ],
  • "idempotency_key": "373fa237-d70e-4177-8139-41354a21c356",
  • "arguments": {
    },
  • "metadata": { }
}

Response samples

Content type
application/json
[
  • {
    }
]

Void funds

This method is used to void (revoke) funds that were reserved when a financial instrument was created.

Releases any withheld funds back to the customer.

A transaction is returned that decreases the available-for-capture amount to zero.

path Parameters
financial_instrument_id
required
string (financial instrument identifier)

The financial instrument identifier returned by the creation request above (instrument_id property).

Request Body schema: application/json
account_id
required
string

The payment account identifier that holds the financial instrument.

instrument_id
string or null

The integrator-owned identifier of the financial instrument that the operation will modify.

required
Array of objects (A financial instrument transaction)

The set of transactions describing the current state of the instrument. The transactions in this array are in no particular order.

idempotency_key
required
string

The request's idempotency identifier and correlation id. This field will be unique for each operation request, but will be the same for retries. The deal with always unique fields, use the retry_id instead.

retry_id
string

The request's unique id. This can be used as an idempotency key, as it will be unique even for retries of a single operation.

required
object

The arguments of the capture/refund operation. In the case of a revoke, these arguments are not provided and the amount and currency are those of the instrument.

metadata
object

Extra information related to this instrument and its payment account. For gift cards, the field 'original_operation' = 'refund' will always be provided. As an integrator, get in touch with your contact point at NewStore to define the metadata you require.

Responses

Request samples

Content type
application/json
{
  • "account_id": "af8e9f4a-b6ec-4677-a9a0-1ff199a8b2ef",
  • "instrument_id": "unique-psp-instrument-identifier-1234567890",
  • "transactions": [
    ],
  • "idempotency_key": "373fa237-d70e-4177-8139-41354a21c356",
  • "arguments": {
    },
  • "metadata": { }
}

Response samples

Content type
application/json
[
  • {
    }
]