What is a payment transfer?

By default, funds for a payment go to a customer's default account and cannot be moved with the exception of withdrawing those funds to a verified external bank account.

Payment transfers can move funds originating from a payment in two ways.

Between accounts for a single customer

All customers can hold several accounts to earmark money for different reasons. Using payment transfers, a customer can move a payment's funds between the various accounts they hold. They can do so any number of times, in any number of directions, over any period of time, so long as funds remain available on the payment (see below for details).

Between customers within the same platform

Platforms can move a payments' funds to and from any customer on its platform. They can do so any number of times, in any number of directions, over any period of time, so long as funds remain available on the payment (see below for details).

🚧

Currency Support

Payment transfer feature is only supported on payments in merchant's base currency.

Transfer Types

Simple transfers

Simple payment transfers should be adequate for most customers' transfer needs.

• Funds will be transferred to the customer listed.
• Only one customer transfer can be specified.
• All funds transferred will be available for withdrawal when the payment goes to paid.
• No followup payment transfers will be allowed on the payment, once the payment is posted.
• Any non-transferred funds will remain on the payment owner.
• Only the "merchant" format and "account" format are supported.

To use simple payment transfers, set the "transferType" to "simple" and include a "transfers" object inside of the payment as follows:

{
  "amount": "100.00",
  "currency": "USD",
  "cardId": "2330cd7d59ac4447804ecf37",
  
  // use simple payment transfers
  "transferType": "simple",
  
  // specify transfers
  "transfers": {
    "acme_corp_platform": "1.23"
  }
  
}

Advanced transfers

• All funds will remain on the payment owner but are transferable after a payment is posted.
• Multiple payment transfer requests can be made.
• Funds flow from and to the payment owner.
• Funds can be held back from being available once a payment goes to paid.

To use advanced payment transfers, set "transferType" to "advanced" on payment creation and then use the payment transfers endpoints to make payment transfers.

{
  "amount": "100.00",
  "currency": "USD",
  "cardId": "2330cd7d59ac4447804ecf37",
  
  // enable advanced payment transfers
  "transferType": "advanced",
  
  // specify transfers
  "transfers": {
    
    // can specify multiple customers/accounts
    "acme_corp_platform": "1.23",
    "acme_corp_sub": "2.23"
    
  }
  
}

Conventions

Structure

The top level keys of the transfers object are the "merchantKeys" for all merchants involved in any of the Payment's transfers. "owner" replaces the "merchantKey" for the payment owner.

The second level keys are the "accountKeys" for the accounts involved in any of the Payment's transfers. "origin" replaces the "accountKey" for the payment's origin account.

The third level contains the keys "final" and "transferable". "final" is the amount of funds that should be added to the account and no longer be able to be further transferred. "transferable" is the amount of funds that should be added or removed from the account and remain available to be further transferred later.

{
  "owner": {
    "origin": {
      "final": "75",
      "transferable": "0.00"
    }
  },
  "acme_corp_platform": {
    "default": {
      "final": "20"
    }
  },
  "acme_corp_sub": {
    "default": {
      "transferable": "10"
    }
  }
}

Formats

There are three supported formats for specifying a payment transfer action.

Merchant format

The merchant format will transfer funds to all of the specified merchants' default accounts and mark them as final.

This format should serve most use cases.

{

  // transfer 1.23 to acme_corp_platforms's default account marked as final
  "acme_corp_platform": "1.23",
  
  // transfer 2.23 to acme_corp_sub's default account marked as final
  "acme_corp_sub": "2.23"
  
}

{
  "{merchant_key}": "{amount}",
}

Account format

The account format will transfer funds to the accounts identified by the accountKey held by the specified merchants and mark them as final.

This format serves use cases that require funds to be transferred to merchants' non-default accounts.

{
  
  // transfer 1.23 to acme_corp_platform
  "acme_corp_platform": {
    
    // to their custom fees account marked as final
    "acme_corp_platform_fee": "1.23"
    
  },
  
  // transfer 2.23 to acme_corp_sub
  "acme_corp_sub": {
    
    // to their default account marked as final
    "default": "2.23"
    
  }
}

{
  "{merchant_key}": {
    "{accountKey}": "{amount}"
  }
}

Expanded format

The expanded format allows for funds to remain transferable.

Using this format will transfer funds to the merchant's given account key. Funds will be marked as final and/or transferable according to the amounts given by the "final" and "transferable" fields.

❗️

Do not forget to eventually mark "transferable" funds as "final"!

Marking funds as "transferable" should be used with caution. It is very important that at some point another transfer be created to mark them as "final". Failing to do so will cause the funds to be unavailable for withdrawal. We recommend keeping close track of all funds marked as "transferable" and marking them as "final" as soon as your business rules allow.

{
  
  // transfer 1.23 to acme_corp_platform
  "acme_corp_platform": {
    
    // to their default account
    "acme_corp_platform_fee": {
      
      // marked as final
      "final": "1.23"
      
    }
  },
  
  // transfer 2.23 to acme_corp_sub
  "acme_corp_sub": {
    
    // to their default account
    "default": {
      
      // marked as transferable
      "transferable": "2.23"
      
    }
  }
}

{
  "{merchant_key}": {
    "{accountKey}": {
      "final": "{amount}",
      "transferable": "{amount}"
    }
  }
}

Final vs transferable fund types

When funds are transferred, they will be marked as "final" or "transferable". Funds that are marked as final can no longer be transferred. Funds that are marked as transferable will remain available to be further transferred, but cannot be withdrawn.

By default, all payment transfers will move funds to "final". The "expanded form" must be used to explicitly indicate that funds should be moved to "transferable".

In the case of advanced payment transfers, when a payment is "posted", all funds will be in the customer's pending balance. When a payment goes to "paid", any funds on a payment marked as "final" will be transferred from the customer's pending balance to their available balance. Any funds marked as "transferable" will remain in the customer's pending balance. Anytime funds move from "transferable" to "final" on a payment, while a payment is "paid", the funds will be transferred from the customer's pending balance to their available balance.

Payment owner

The payment owner is special in that they cannot be referred to in a payment transfer via their merchantKey. The key "owner" must be used instead. See the following examples:

{
  
  // mark 20 on origin account as final
  "owner": "20.00",
  
  // send 20 to owner
  "owner": {
    
    // to their non-origin account and mark as final
    // note: you cannot use the origin account here
    "california_funds": "20.00"
    
  },
  
  // transfer 20 to owner 
  "owner": {
    
    // to their california_funds account
    // note: you cannot use the origin account here
    "california_funds": {
      
      // mark 10 as final
      "final": "10.00",
      
      // mark 10 as transferable
      "transferable": "10.00"
      
    }
  }
  
}

Origin account

Similar to the "owner" key, the origin account for the payment cannot be referenced via its account key. It must always be referenced by the key "origin". In addition, the fund type "transferable" cannot be used inside of the "origin" account.

{

  "owner": {
    
    // correct: mark 20.00 in the origin account as final on the owner
    "origin": "20.00",
    
    // invalid: will attempt to reduce the "final" balance
    "origin": "-20.00",
    
    "origin": {
      
      // correct: mark 20.00 in the origin account as final on the owner
      "final": "20.00",
      
      // invalid: can't reference transferable key on the origin account
      "transferable": "20.00"
      
    }
    
  }

}

Transferring in and out

All payment transfers act relative to the payment's origin account.

Origin account sending funds

A positive amount for a payment transfer indicates that funds should move out of the origin transferable account into the designated merchant's account. When "final" or "transferable" are not specified, the sent funds will be marked as "final".

Origin account receiving funds

A negative amount for a payment transfer indicates that funds should move from the merchant's designated account into the origin's transferable account.

{
  
  // sending:
  // transfer to acme_corp_platform
  // from origin account
  // mark funds as final
  "acme_corp_platform": "1.23",
  
  // receiving:
  // transfer to origin account
  // from acme_corp_sub's default account
  // keep funds marked as transferable
  "acme_corp_sub": "-2.23"
  
}

Transfer objects

When payment transfers are initiated, several objects are also created to help keep track of the flow of funds.

Payment balance change

A payment balance change object will be returned when a request is made for a payment transfer. Every fund movement related to a payment will be recorded by a "payment balance change" record.

The "change" key represents the expanded form of a payment transfer request, with the addition of the origin's "transferable" account shown.

Usually the "acting resource" is the payment. In the case of refunds, disputes, and recoups, which also create payment transfer actions, the acting resource will be a refund, dispute, or recoup respectively.

_final vs final

When a payment is posted, the "final" account is denoted as "_final" instead of "final".

{
  "id": "h3qo5rine8itrr43wfen2356",
  "object": "paymentBalanceChange",
  "paymentId": "crjeild6qpfse3a09vhtxw",
  "actingResourceId": "crjeild6qpfse3a09vhtxw",
  "actingResourceType": "Payment",
  "change": {
    "owner": {
      "origin": {
        "final": "20.00",
        "transferable": "-30.00"
      }
    },
    "acme_corp_platform": {
      "default": {
        "final": "10.00",
        "transferable": "0.00"
      }
    }
  },
  "status": "complete",
  "created": "2018-10-28T22:55:09.000Z",
  "lastUpdated": "2018-10-28T22:55:13.000Z"
}

Payment balance

A payment's balance shows, at the current time, the location of all funds related to the payment. All changes to a payment's balance originate from a payment's balance actions.

Like the balance change object, the payment balance object is of the same form as a payment transfer, with the exception that the origin's "transferable" account is shown.

_final vs final

When a payment is posted, the "final" account is denoted as "_final" instead of "final".

{
  "owner": {
    "origin": {
      "final": "20.00",
      "transferable": "-30.00"
    }
  },
  "acme_corp_platform": {
  	"default": {
      "final": "10.00",
      "transferable": "0.00"
    }
  }
}