Payment Service Automatic Recharge Retry

The Payment Service can retry a payment authorization for system-initiated automatic recharges when the associated Payment Gateway Provider supports retries.

When the Payment Service sends a request to a Payment Gateway Provider, the payment transaction can succeed or fail. If the Payment Gateway Provider sends a result code SUCCEEDED (1), the request succeeded and there are no retires. If the transaction fails, result codes returned by the Payment Gateway Provider indicate the type of the failure. During Payment Service configuration, you must map codes returned by the Payment Gateway Provider to the following Payment Service codes:

FAILED (2) — Indicates that a request has failed and it cannot be retried. A retry could result in duplication. There is no notification for failed automatic recharge requests.
FAILED_TRANSIENT_SYTEM (3) — Indicates that the request failed (due to a timeout or system busy issue), but can be retried without the risk of duplication. For example, this could happen if the payment gateway is inaccessible. There is no notification for system failures.
FAILED_TRANSIENT_USER (4) — Indicates that the request failed, but can be retried without the risk of duplication. These errors require user intervention. For example, this could happen if the user-supplied credentials are wrong. The Charging Server sends a notification for user failures.

Note: For Payment Gateway Provider failure codes for a specific payment gateway, see the documentation from that Payment Gateway Provider.

The Payment Service sends these result codes to the Charging Server.

If retries are configured for a Payment Gateway Provider and an automatic recharge request fails with result code 3 or 4, it is retried if the maximum number of retries has not been reached. For result code 2, the authorization fails and there are no retries.

When the maximum number of retries is reached, the authorization fails with a timeout error indication. If a transaction times out, the authorization request is finished and no more retries are attempted. For information about maximum retry and timeout configuration, see the discussion about retry configuration.

To configure retries for a Payment Gateway Provider, you must define the following information in the payment-service.yaml file:

payment:
  gateway:
    adapter_name:
      configs:
        default: 
          retryOperations: [List of operations that support retries]
          transactionErrors: {Payment Service Error Code: [List of Payment Gateway Error Codes]} 
          transportErrors: [List of User Error Codes]

Where:

List of operations that support retries — A comma-separated list of Payment Gateway Provider operations that support retries. For example, 7 (authorize and capture).
adapter_name — A supported Payment Gateway Adapter. For example, braintree.
Payment Service Error Code — A Payment Service error code (3 or 4).
List of Payment Gateway Error Codes — A Payment Gateway Provider error code. For example, 2034.
List of User Error Codes — HTTP errors that are considered to be failed transient system statuses. For example, 10.

For information about payment gateway extension MDC fields for each Payment Gateway Provider, see the discussion about the Pay Now authorization process.

For information about configuring a specific Payment Gateway Adapter, see the discussion about Pay Now Payment Gateway Adapters. For more information about the result and response extension fields, see the discussion about the Pay Now authorization process.

In the following examples, retryOperations values indicate authorize and capture and transportErrors indicate a timeout. For each of the transportErrors mapping configurations, the payment service returns a failed transient system status rather than a failed status.

Braintree Retries

The following example shows a Braintree retry configuration in the payment-service.yaml file:

payment:
  gateway:
    braintree:
      configs:
        default:
      retryOperations: [ 7 ]
      transactionErrors: {3: [ "2034" ], 4: [ "2001" ]}
      transportErrors: [ 10 ]

Foo Masterpass Retries

The following example shows a Foo Masterpass retry configuration in the payment-service.yaml file:

payment:
  gateway:
    foomasterpass:
      configs:
        default:
          retryOperations: [ 7 ]
          transactionErrors: {3: [ "850", "851" ], 4: [ "913", "914" ]}
          transportErrors: [ 408 ]

RomCard Retries

The following example shows a RomCard retry configuration in the payment-service.yaml file:

payment:
  gateway:
    romcard:
      configs:
        default:
          retryOperations: [ 7 ]
          transactionErrors: {3: [ "99" ], 4: [ "51" ]}
          transportErrors: [ 404, 412 ]

Notifications

A notification (MtxPaymentMethodUpdateRequestNotification) is generated when a payment authorization request to the Payment Service results in a FAILED_TRANSIENT_USER result code. Notifications are not generated for transient system failure retries.

For more information about MtxPaymentMethodUpdateRequestNotification, see the discussion about notification data relationships in MATRIXX Integration.