Payments and transfers
For any new deployments, the recommendation is to use the enhanced Payment methods API instead of the Transfer funds and Cancel transfer endpoints described in this guide. All new feature developments will be available only in the Payment methods API. For more information, contact your Pismo representative.
The Pismo Payments API allows you to transfer funds between accounts inside the platform, perform cash-in and cash-out operations between accounts or external entities, use the customer's balance or credit cards to pay invoices, and more.
The transactions that can take place on the Pismo platform can be grouped into three categories:
- cash-in, where money is deposited to the platform account from an external environment
- internal transfer, where money is transferred between the platform accounts
- cash-out, where money is withdrawn from the platform account to an external environment
The diagram below illustrates your possibilities:
Here some examples of common fund transfers you can make in the Pismo platform:
- transfer between two Pismo platform accounts (P2P)
- transfer using a card on file
- cash-in from an external entity into a Pismo account
- cash-out from a Pismo account to an external entity
- payment responding to a payment request
Anatomy of a transfer request
In the request, the from
array determines the sending party and the to
array determines the receiving party. Both arrays can contain one of the objects: account
, card
, custom_info
, or merchant
. The structure of these arrays determines the type of transfer operation to be performed. You can pass along any additional information using the metadata
object.
When requesting a transfer, two structures are worth noting: the payment method and the processing code.
Payment method
The transfer data structure that is sent as a payload to the Payments API has two fundamental objects that determine what operation is being made. The from
and to
objects describe the source of the funds and its destination, and can contain one of the following nested structures:
Object | Description |
---|---|
account | Identifies an account inside the Pismo platform. |
card | Contains details of a tokenized credit card previously stored in a wallet in the Pismo PCI environment. Go to Wallet overview if you want to learn more about tokenized cards. |
custom_info | Describes custom payment information, usually about an external entity, which can be a checking account, debit card, or any other source destination. |
merchant | Identifies a merchant account inside the Pismo platform. The merchant receives the money on the receivable schedule according to the agreement between the marketplace and the merchant. |
Combining these objects in the from
and to
properties determines if the funds are being collected in an account, transferred between the two of them, or sent to an external entity.
To: account | To: card | To: custom_info | To: merchant | |
---|---|---|---|---|
From: account | Pismo account to Pismo account (P2P) | Not available | Cash-out of unregistered partnerships (for example, withdrawal or pay invoices) | Pismo account to Pismo merchant account (P2M) |
From: card | Transfers with tokenized cards (wallet): - P2P with card on file (COF), where the account IDs are different - Cash-in with COF, where the account IDs are the same | Not available | Cash-out of unregistered partnerships with COF (for example, slip payment) | Pismo account to Pismo merchant account (P2M) with COF |
From: custom_info | Cash-in of unregistered partnerships (for example, pay invoice) | Not available | Not available | Not available |
From: merchant | Not available | Not available | Not available | Merchant to merchant account (M2M) |
Processing code
If the source (from
) and destination (to
) structure defines what kind of operation is being made (a cash-in, a peer-to-peer, or a cash-out), the processing code describes how this operation is treated internally and the type of transaction that will be generated. For instance, the way that the balance account will be impacted and if the operation needs to involve a validation by an external acquirer are operational pieces of information associated with a processing code. Processing code also defines the type of associated transaction generated and how it will be handled in accounting.
Examples
P2P with COF example
{
"from":[{
"amount":150,
"currency":"USD",
"card": {
"id": "a9081236-58de-4ce2-9918-8440ede19032",
"account_id": 123
}
}],
"to":[{
"account":{
"id":125487
}
}]
}
Cash-out with processing code example
{
"from":[{
"amount":150,
"currency":"USD",
"processing_code": "007000",
"account":{
"id":125487
}
}],
"to":[{
"custom_info": {
"external_id": "721-00047551-4",
"type": "Bank transfer",
"name": "John Doe",
"description": "Transfer to National Bank"
}
}]
}
Cash-in with metadata example
{
"from":[{
"custom_info": {
"external_id": "5512990-642",
"type": "Deposit"
}
}],
"to":[{
"amount":100,
"currency":"USD",
"account":{
"id":342485
}
}],
"metadata":{
"sender": "Andrew Foster",
"bank": "OneBank",
"branch_code": "0089",
"account_id": "13000-7"
}
}
For detailed reference information on how to create different transfers in the Pismo platform, go to Transfer funds.
For examples of different transfers, go to Make transfer.
Updated about 2 months ago