Process delegated payments

Configure InStore to create only a minimal commercetools Payment resource and delegate its population to your payment processor.

Process delegated payments

InStore supports two ways to create and populate the commercetools Payment resource for a tender:

InStore-managed payments (default): the InStore API Server creates and populates the Payment resource, including its transactions, for you.
Delegated payments (described in this topic): InStore creates a minimal Payment resource with amountPlanned. It passes the ID to your payment processor. Your payment processor populates the Payment resource, including its transactions. It sets paymentStatus.interfaceCode to "Success".

Use delegation when you want your payment processor to populate Payment and Transaction Custom Fields to match those used in your other checkout integrations. It also makes the tender flow more resilient to connection errors between the client, the InStore APIs, and the payment processor.

Cash payments are always created by InStore and don't support delegation. Delegated creation also doesn't apply to the built-in InStore POS integrations with Stripe and Adyen.

For more information about delegated returns and refunds, see the InStore_Refund module.

Supported payment processor types

Delegation is available for the following payment processor types:

BankCard
GiftCard (Stored Value)

For each supported type, set integrationConfiguration.delegatePaymentCreation to true when you create the payment processor. If you omit the field, it defaults to false and existing processors keep the default creation behavior.

The field name and its location in the payload differ by processor type. Use the exact form shown for each type below.

Delegated flow

When delegatePaymentCreation is true, the payment flow changes as follows:

InStore creates a minimal Payment resource that contains only the amountPlanned field.
- For BankCard, the route is collect_credit_payment.
- For GiftCard, the route is storedvaluecard_process.
InStore passes the ID of the minimal Payment resource in the payment request to your payment processor:
- For BankCard, the field is payload.paymentId.
- For GiftCard, the field is payload.payment_id.
For details on the request payloads, see the payment extensions reference.
Your payment processor populates the Payment resource in commercetools, including its transactions for the full amount.
Your payment processor sets paymentStatus.interfaceCode to the literal string "Success" and adds successful transactions whose amounts total the Payment resource amountPlanned.centAmount.

Return the response to InStore

InStore expects to receive your payment service provider's response to the payment request. Use the same structure as described in Send InStore the final result of an asynchronous payment.

Delegated payments have an additional requirement. Include the Payment resource ID that InStore created in step 1 and sent in the payload object. The field name and its location in the response differ by processor type.

BankCard response

For BankCard, follow the format described in the Credit payment extension topic. InStore expects paymentId inside data:

Sample BankCard payment processor responsejson
{
  "result": "Success",
  "data": {
    "paymentId": "234672673467236742"
  }
}

GiftCard response

For GiftCard, follow the format described in the GiftCard payment extension topic. InStore expects payment_id at the top level:

Sample GiftCard payment processor responsejson
{
  "result": "Success",
  "payment_id": "234672673467236742"
}

Attach the payment to the cart

For both BankCard and GiftCard delegated flows, InStore only validates that the Payment ID exists. InStore does not automatically link the Payment resource to the cart. You must attach the Payment resource to the cart using the addPayment update action on one of the following endpoints.

Attach a Payment to a cart by IDhttp
POST /{projectKey}/carts/{id}

Attach a Payment to a cart by keyhttp
POST /{projectKey}/carts/key={key}

Process delegated payments