Developer checklist
Technical considerations
Object identifiers
Assembly can track your User Identifiers (IDs) and Item IDs to identify objects.
This is a default feature that makes it easier to track these objects within Assembly. By doing this, you do not need to store any Assembly generated User or Item identifiers. Instead, you can pass your IDs on creation.
Users and Items are the primary objects of Assembly and through these, you can access every piece of data stored in the system.
There are multiple formats that can be used when sending us a User or Item ID:
| Type | Description | Example |
|---|---|---|
| Existing ID | You may already be tracking an ID for a User or Item. You can pass us this when you create the User or Item object. | item001 |
| UUID | A universally unique identifier which can ensure a unique index. | 59188265-9f38-4f1f-b9b0-8541a7905ea1 |
| Combined Item ID with Buyer ID | This combination is often used when creating Items that have buyer’s bidding for the same goods/services on your platform. This method avoids having duplicate Item Identifiers created in Assembly. | item001_buyer001 does not conflict with item001_buyer002. |
| Generated UUID | A UUID generated by Assembly that you will need to store within your system. Contact Assembly if you wish to have this enabled. | 59188265-9f38-4f1f-b9b0-8541a7905ea1 |
Storing Data
There are certain data elements produced and processed in Assembly that may need to be stored within your database for future reference. These are commonly related to identifiers, statuses and API responses. Some examples of these are:
| Type | Description | Example |
|---|---|---|
| User/Item IDs | If you opt for Assembly generated IDs, they will need to be stored against the relative User/Item object in your platform. | 59188265-9f38-4f1f-b9b0-8541a7905ea1 stored against a row in your ‘customers’ or ‘users’ table. |
| Item Status | The most important piece of data for an Item is the ‘state’. This state represents whether an Item is pending, in progress or completed. | This can be stored to ensure that once an interaction on your platform is complete, no further calls are made to Assembly. |
| User KYC State | The User’s KYC state changes when Assembly verifies the User’s data. | The KYC state can be stored and used to restrict certain functions available for your users. For example, you may wish to restrict Transaction amounts depending on a User’s status. |
| API Responses | Storing API responses from a third party is common practice in software development. It involves storing the response (including headers) received from an Assembly API request. | This can be used to track whether payment calls were successful and to track the reason why a card may have been declined. |
To reduce the number of API calls required throughout a complex payment workflow, we suggest storing a map of IDs on your platform. For example:
| Your platform customer ID | Assembly user ID | Assembly bank account ID | Assembly 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 |
Email Addresses
Emails are a required piece of data for a user to be onboarded in Assembly. By default, an email address is unique in Assembly. This restriction is designed for a platform that has both registered buyers and sellers, with unique email addresses.
Your platform may not need to know the identity of users, which means you may not have an email address to pass to Assembly until during the payment process. If this is the case, then you will need to contact Assembly to disable the unique email feature.
Monitoring
There are a number of ways to monitor the uptime and status of the Assembly service. You can visit status.assemblypayments.com to see any incident reports that have occurred. Furthermore, there is an endpoint available to check the status of the API service.
Authentication
Interacting with Assembly primarily occurs via the APIs, however, there are some front-end features that are provided to help with PCI compliance, fraud & risk and user experience. Providing trust on a platform which handles payments results in dealing with a large amount of sensitive information.
When providing sensitive information to Assembly, you must ensure authentication is provided appropriately. Your API credentials should only be exposed within the back-end of your system and not on the front-end. Making your API credentials publicly available potentially enables an unauthorized person to interact with the accounts and information of your users.
When using PromisePay.js and authenticating on the front-end, an expirable token will always need to be generated on the back-end first, ensuring that the API key is never exposed.
For more information relating to authentication please refer to Authentication
Tokens
| Token | Description |
|---|---|
| API credentials | A combination of client code, secret and scope that is generated for your platform. Contact Assembly if you need new credentials generated. |
| Card token | This token is used with the PromisePay.js package to pass credit card details securely to Assembly for a certain User. |
Callbacks
Many statuses and actions occur within Assembly through several batch processes that run throughout each day. Because of this, callbacks are essential to closing the loop of an Assembly integration and are helpful to present back to users so that they understand where they’re currently at within a transaction.
Callbacks can be sent from a number of IPs that will need to be whitelisted, different for each environment .
Updated over 3 years ago