This guide covers testing and integration best practices for submitting a single payment method against either a single gateway or multiple gateways. Single method, single gateway is the simplest setup to implement and test. If you're using gateway tokens across multiple gateways, careful token-to-gateway_code hygiene is essential for a successful implementation.

1Definition 2Integration guide

Prerequisites and limitations

You've reviewed the basic API guide and are familiar with the fields on the Recovery endpoint
You've enabled one or more gateways on your Recurly sandbox site
You know which gateway tokens are accessible through your enabled gateways. For example, if you provide Recurly with Braintree gateway tokens, your enabled Braintree gateway must have access to them
If your gateway tokens require a Network Transaction ID (NTID), you have the NTIDs available for Recurly to store and send. Stripe, Braintree, and PayPal Complete are exceptions — for any other gateway, provide the NTID you use for normal subscription processing

Definition

Creating a recovery invoice means generating a new invoice through the Recurly API specifically to retry collection on a failed or past-due subscription charge, without disrupting the original billing cycle or subscription state. This guide covers submitting a single payment method against either a single gateway or multiple gateways.

Integration guide

Best practices

Use the original gateway and merchant account the customer's subscription was set up on — this gives you the best chance of success
Confirm the token exists on the target gateway. Tokens are typically tied to the specific gateway account they were created on, so specifying a different account can cause an error
Pass the NTID on any gateway that requires it and doesn't handle storage on your behalf or Recurly's
When using tokens across multiple gateways, submit a separate token for each gateway that represents the same payment method. For example, to have Recurly attempt a single Visa card on both Stripe and Braintree, you'll need a token from each gateway, even though they represent the same underlying card. Review Multiple payment methods best practices to make sure your testing is complete

Example: single payment method, single gateway

{
  "currency": "str",
  "due_at": "2019-08-24T14:15:22Z",
  "po_number": "string",
  "external_recovery_eligible": true,
  "account": {
    "address": {
      "phone": "string",
      "street1": "string",
      "street2": "string",
      "city": "string",
      "region": "string",
      "postal_code": "string",
      "country": "string"
    },
    "billing_infos": [
      {
        "first_name": "string",
        "last_name": "string",
        "company": "string",
        "address": {
          "phone": "string",
          "street1": "string",
          "street2": "string",
          "city": "string",
          "region": "string",
          "postal_code": "string",
          "country": "string"
        },
        "ip_address": "string",
        "gateway_code": "string",
        "primary_payment_method": true,
        "backup_payment_method": true,
        "payment_gateway_references": [
          {
            "token": "string" // Single-part Tokens Only
          }
        ],
        "network_transaction_id": "string",
        "transactions": [
          {
            "gateway_error_code": "string",
            "merchant_advice_code": "st",
            "attempted_collection_date": "2019-08-24T14:15:22Z"
          }
        ]
      }
    ],
    "code": "string",
    "email": "[email protected]",
    "custom_fields": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "dunning_campaign_id": "string"
  },
  "line_items": [
    {
      "tax": 0,
      "custom_fields": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "harmonized_system_code": "string",
      "product_code": "string",
      "quantity": 1,
      "description": "string",
      "unit_amount": 0
    }
  ]
}

Stripe Formatting

If you are using Stripe, the PGR array is formatted in the following manner as Stripe has two-part tokens. You must provide the Customer ID and the Payment Method ID as below.

 "payment_gateway_references": [
          {
            "token": "string",
            "reference_type": "stripe_payment_method"
          },
          {
            "token": "string",
            "reference_type": "stripe_customer"
          }
        ],

For next steps and error handling, follow our dedicated integration guide: Submit Invoices via Recovery API