Cards Payin Workflow

Overview

This integration guide will run you through how to use cards to fund an item through a user's wallet account.
You will need to capture a user's card details into a card account and then create an item between buyer/payer and seller/payee. Afterwards you perform a make payment action on that item specifying the card account of the buyer/payer.

Getting Started

Before you can run your cards workflow there are a few setup steps that need be completed so that all of the pieces are available.

Terminology used
The following terminology is used throughout this guide:

• Platform​ refers to your platform (website, app, marketplace etc.).
• User​ refers to your customer who will have a User record in Assembly.
• Item​ is the mechanism for moving funds between users in the API.
• Payin​ is money being paid into the Assembly ecosystem.
• Payout​ is money being paid out of the Assembly ecosystem to a bank account.
• ASM​ is shorthand for Assembly
• Card account is an account attached to a user that contains encrypted card details

API steps

1. Create a buyer ​user​ in Assembly.
   POST /users
2. Create a card account for the buyer Card Accounts. Please make sure you store the card account id as you will need that later on when making the payment.
   POST /users/:id/card_accounts
3. Create a seller ​user​ in Assembly.
   POST /users
4. Create an item Create Item between the buyer and the seller without the amount
   POST /items
5. (Once off) Set up ​Callback​ (webhook) on the ​items​ object to be notified of when the item status changes
   POST /callbacks

"object_type": "items",

6. (Once off) Set up ​Callback​ (webhook) on the ​transactions​ object to be notified of when the card transaction is authorised on the buyers card
   POST /callbacks

"object_type": "transactions",

7. (Once off) Set up ​Callback​ (webhook) on the Batch Transactions object to be notified of when the card transaction is settled and the funds are moved to the seller's wallet
   POST /callbacks

"object_type": "batch_transactions",

8. Call Make Payment on the item and specify the card account id (obtained from step 2)
   PATCH /items/:id/make_payment

Once the the make_payment API has been called, Assembly will attempt to authorise the payment against the card account. This will result in the card being debited and if successful, the following steps will occur:

9. The item status will move to completed and you will receive an items callback indicating the item is completed and the item will have the value of released_amount equal to 0 initially.

10. You will also receive a transactions callback indicating that the transaction of type: payment and type_method: credit_card is successful.

11. Only after the card transaction settles (this could vary between 1-2 business days based on your settings) the funds will be applied to the seller/payee's wallet account. As part of that you will receive a batch_transactions callback of type: payment_funding and type_method: credit_card with a status of successful. Additionally, you will also receive another callback for items with the value of released_amount equal to the value of the item amount.

**In PreLive you can:

12. (Pre-Live only) Call the following API which moves all pending batch_transactions into batched state. As a result this API will return all the batch_transactions that have moved from pending to batched.
    GET /batch_transactions/export_transactions

{
    "transactions": [
        {
            "id": "439970a2-e0a1-418e-aecf-6b519c115c55",
            "batch_id": null,
            "status": "batched",
            "type": "payment_funding",
            "type_method": "credit_card"
        }
    ]
}

13. (Pre-Live only) You can call the following API which moves one or more batch_transactions into bank_processing state 12700. You will need to pass in the id from step 12.
    PATCH /batches/:id/transaction_states

{
	"exported_ids" : ["439970a2-e0a1-418e-aecf-6b519c115c55"],
	"state": 12700
}

{
    "aggregated_jobs_uuid": "c1cbc502-9754-42fd-9731-2330ddd7a41f",
    "msg": "1 jobs have been sent to the queue.",
    "errors": []
}

14. (Pre-Live only) You can call the same API from the step above to move one or more batch_transactions to the final state of processing being successful state 12000 . This will simulate the step of the flow where we complete the processing of the card funding for the payment and will result in you receiving a batch_transactions webhook
    PATCH /batches/:id/transaction_states

{
	"exported_ids" : ["439970a2-e0a1-418e-aecf-6b519c115c55"],
	"state": 12000
}

{
    "aggregated_jobs_uuid": "c1cbc502-9754-42fd-9731-2330ddd7a41f",
    "msg": "1 jobs have been sent to the queue.",
    "errors": []
}

If you are after more information on the item, transactions or batch_transaction you can query them using their ids

/batch_transactions/dabcfd50-bf5a-0138-7b40-0a58a9feac03

Design considerations

When designing how this workflow will interface with your platform, we suggest storing a map of specific object IDs on your side in order to reduce the number of API calls required throughout the API workflow.

User data design

Payin data design

General Information

For capturing card details securely while reducing your PCI obligations please refer to:
Integrating Drop-in UI for Capturing a Credit Card

For the different set of details you would receive in callbacks and some sample callbacks please refer to: Callbacks

For test data to use when creating a card please refer to: Test data