---
title: "Configuring payment providers"
slug: "configuring-payment-providers"
tags: ["config api", "Adyen ", "Google Pay", "Associate App", "Tap to Pay on iPhone", "NewStore checkout", "platform", "exchange", "payment", "payment options", "refund", "Apple Pay", "tutorial", "api", "PayPal", "gift card", "Square"]
updated: 2026-07-07T09:35:57Z
published: 2026-07-07T09:35:57Z
canonical: "docs.newstore.com/configuring-payment-providers"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newstore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuring payment providers

To set up payments, configure the:

- **Payment providers** that you integrate or need, to process payments, refunds, and exchanges.
- **Payment strategies** that include the available payment methods and the hierarchy that decides which methods are used to capture payments and refund them.

## Configuring payment providers

1. Retrieve the current configuration using the [Get FAT PSP configuration](https://docs.newstore.net/api/configuration/payment/payment_config_api#operation/getFATPSPConfiguration) method.
2. Go to the fat_psp > `external_providers` key.
3. Add a new entry to the `external_providers` key for each provider that you want to integrate with.

To be able to process payment transactions from gift cards, add your gift card provider as an external provider here. To enable gift card operations through integrations, also [add a gift card provider here](/v1/docs/configuring-payment-providers#configuring-gift-cards-as-a-payment-strategy).

1. For each entry, specify these values for the following configurations:
  1. `callback_url`: The payment provider's service URL for which to post requests. Also see [Payment provider webhooks](https://docs.newstore.net/api/webhooks/fat_psp_hook) and `integ-psp`.
  2. `timeout`: The maximum amount of time in seconds to wait for the response when calling the payment provider URL.
2. Apply the updated configuration using the [Update FAT PSP configuration](https://docs.newstore.net/api/configuration/payment/payment_config_api#operation/putFATPSPConfiguration) method.

> [!TIP]
> Note
> 
> FAT - Financial Apparatus Transformation
> 
> PSP - Payment Service Providers
> 
> fat_psp service is the payment service provider gateway for the platform. It is responsible to find the correct PSP and normalize the commands requested from payment_account service.

## Configuring payment strategies

NewStore Omnichannel Cloud allows you to configure the following 3 payment strategies for your business:

### Configuring a hierarchy for payment methods

The `ordered` strategy allows you to define a hierarchy for the payment methods that the your business supports. To specify this payment strategy:

1. Retrieve the current configuration using the [Get payment account configuration](https://docs.newstore.net/api/configuration/payment/payment_config_api#operation/getPaymentAccountConfiguration) method.
2. In the `available_strategies` > `ordered` key, add an array of payment methods that can be used to capture payments or issue refunds. The payment methods are executed in the order in which they exist in the array.

For example, if you added `credit_card` and `cash`, the payments made via credit card are captured first before capturing cash payments.

> [!NOTE]
> Important
> 
> To avoid potential issues with split payments for your business, ensure that you add `cash` as the first payment method in `ordered`.
3. Apply the updated configuration using the [Update payment account configuration](https://docs.newstore.net/api/configuration/payment/payment_config_api#operation/putPaymentAccountConfiguration) method.

### Configuring exchanges as a payment strategy

The `store credit` strategy allows you to process exchanges.

> [!TIP]
> Note
> 
> When a customer exchanges an item, the exchange amount for the item is held as `store_credit`, temporarily, until the exchange is complete. This reduces the number of payments transactions processed in NewStore Omnichannel Cloud. For uneven exchanges, a new financial instrument is created for the balance amount. For more information, see [Integrating a payment service provider](/v1/docs/integrating-a-payment-service-provider#integ-psp).

1. Retrieve the current provider configuration using the [Get FAT PSP configuration](https://docs.newstore.net/api/configuration/payment/payment_config_api#operation/getFATPSPConfiguration) method.
2. Add `store_credit` to the `internal_providers` key.
  1. Set `endpoint` to `/store_credit.StoreCredit/Execute`.
  2. Set `protocol` to `grpc`.
  3. In `timeout`, set the maximum amount of time (in seconds) allowed when calling the service.

We recommend specifying a timeout of `30` seconds.
3. Apply the adjusted configuration using the [Update FAT PSP configuration](https://docs.newstore.net/api/configuration/payment/payment_config_api#operation/putFATPSPConfiguration) method.
4. Retrieve the current strategy configuration using the [Get payment account configuration](https://docs.newstore.net/api/configuration/payment/payment_config_api#operation/getPaymentAccountConfiguration) method.
5. Add `store_credit` to the `available_strategies` key.
6. Apply the updated configuration using the [Update payment account configuration](https://docs.newstore.net/api/configuration/payment/payment_config_api#operation/putPaymentAccountConfiguration) method.

### Configuring gift cards as a payment strategy

The `gift_card` strategy allows you to process payments via gift cards.

To accept gift card payments and issue refunds:

1. Add `gift_card` as an external provider. See `config-payment-providers`.
2. Retrieve the current strategy configuration using the [Get payment account configuration](https://docs.newstore.net/api/configuration/payment/payment_config_api#operation/getPaymentAccountConfiguration) method.
3. Add `gift_card` to the `available_strategies` key.
4. Apply the updated configuration using the [Update payment account configuration](https://docs.newstore.net/api/configuration/payment/payment_config_api#operation/putPaymentAccountConfiguration) method.

#### Enabling gift card operations

To enable operations like issuing and activating gift cards:

1. Retrieve the current gift card configuration using the [Get gift card configuration](https://docs.newstore.net/api/configuration/payment/payment_config_api#operation/getGiftCardConfiguration) method.
2. Set the provider's service URL in the `provider` > `endpoint` key.
3. Set the gift card provider's name in the `provider` >`name`` key.
4. If you sell gift cards as products, to identify a gift card as a product in the cart during checkout, specify the gift card ID in the `provider` > `gift_card_ids` list.
5. Apply the adjusted configuration using the [Update gift card configuration](https://docs.newstore.net/api/configuration/payment/payment_config_api#operation/putGiftCardConfiguration) method.

Also see [Integrating a gift card provider](/v1/docs/integrating-a-gift-card-provider#integ-giftcard) and [Gift card webhooks](https://docs.newstore.net/api/webhooks/gift_card_hook).

### Configuring default capture and refund strategies

The default capture strategy is used for capture operations when items are handed over or shipped, while the default refund strategy is used for refunds to original payment methods and appeasements. These configurations do not affect other refund options. For more information, see [Configuring refund options](/v1/docs/configuring-refund-options#config-refund-options).

To change the configured values:

1. Retrieve the current strategy configuration using the [Get payment account configuration](https://docs.newstore.net/api/configuration/payment/payment_config_api#operation/getPaymentAccountConfiguration) method.
2. In the `default_capture_strategy` property, set one of the values from the `available_strategies` as the default strategy to capture payments. `ordered` usually fits most business requirements.
3. In the `default_refund_strategy` property, set one of the available strategies as the default strategy to process refunds to original payment methods. Some example behaviors:
  - If set to `gift_card`, refunds can only be issued as gift cards.
  - If set to `ordered`, the refunds happen to payment methods with amounts available for refunds in the order described in `available_strategies` > `ordered`. Payment methods not listed are considered after the listed ones, in no particular order.
4. Apply the adjusted configuration using the [Update payment account configuration](https://docs.newstore.net/api/configuration/payment/payment_config_api#operation/putPaymentAccountConfiguration) method.

**Related topics**

- [Configuring refund options](/v1/docs/configuring-refund-options#config-refund-options)
- [Placing orders](/v1/docs/placing-orders#shopping-api)
- [Integrating a payment service provider](/v1/docs/integrating-a-payment-service-provider#integ-psp)
- [Integrating a gift card provider](/v1/docs/integrating-a-gift-card-provider#integ-giftcard)
- [Integrating Adyen](/v1/docs/integrating-adyen#integ-adyen)

FAT - Financial Apparatus Transformation

PSP - Payment Service Providers

fat_psp service is the payment service provider gateway for the platform. It is responsible to find the correct PSP and normalize the commands requested from payment_account service.