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",
  1. (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",
  1. (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",
  1. 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:

  1. 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.

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

  3. 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:

  1. (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"
        }
    ]
}
  1. (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": []
}
  1. (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

your_customer_id

asm_user_id

asm_card_account_id

asm_digital_wallet_id

10001001

5b8f59b6-32c1-44a3-8f5b-b9e2c77bc265

fb35b028-76fb-44df-86ac-822dccf1cd7d

dcdfdb78-27e7-485d-90c0-11ffbf950d72

10001002

efe6f8c1-0a30-484a-b085-9d9d0539dbfc

4355de7b-18c2-4892-b800-b7bbb6f0a9b3

054cd04e-19f1-4938-908b-8e9e5c212f4d

Payin data design

your_payin_id

asm_item_id

asm_transaction_id

asm_batch_transaction_id

30001001

1563db1c-add2-4dcd-ae20-5ad3802bf1c4

1ddb9cbb-90a7-41c6-bbbe-05e44f3134f1

54504fea-68cf-4154-b16b-ac7b747c4e20

30001002

f827dbb5-ba17-4241-a282-14336351faff

445bbaf3-c9bc-41aa-aec4-c9a99944941d

d43ad47d-fb2d-46b2-bc3d-a623a290cdac

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


Did this page help you?