# Create new order: Posting an offer for your customer

If you have followed the previous steps you are now ready to create your first order!

WARNING

BEFORE THIS REQUEST IS SENT, THE BANK MUST HAVE SUCCESSFULLY PUT THE REQUIRED HOLD ON THE CUSTOMER'S FUNDS.

The poster-recipient-username is the registered email address of your customer's beneficiary. This is the Kaoshi user who your customer wishes to send money to.

The poster-recipient-username must be a valid Kaoshi account and must have a valid bank account setup for receiving payment.

For testing purposes please use janeth-usa-receiver@example.com as the poster's beneficiary.

TIP

Before posting an offer, ask your customer for the first name, last name, and handle of their beneficiary. Then use the get Kaoshi info endpoint to get the beneficiary's info and compare the names to verify the handle was entered correctly.

An example request to create an order is below. The fields are defined in table 1 below.

curl --location --request POST 'https://app.sandbox.kaoshinetwork.com/api/api/v1/order/create' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer secret-api-token' \
--data-raw '

{
  "poster_username": "joy-nigeria-sender@example.com",
  "poster_recipient_username": "janeth-usa-receiver@example.com",
  "poster_currency": "NGN",
  "poster_country": "NG",
  "poster_amount": "180750.00",
  "poster_payment_method_type": "nigerian_bank_payment",

  "matcher_currency": "USD",
  "matcher_country": "US",
  "matcher_amount": "500",

  "exchange_rate": "361.5",
  "external_order": {
  	"current_account_balance": "123123.12",
  	"transaction_fee": 123.12,
  	"transaction_fee_currency": "NGN"
  }
}

'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

Below is an illustration of the relevant "Create New Order" API parameters and their corresponding fields on the pertinent user interface.

Post your offer

Next is the confirmation order dialogue box. This is an illustration of the "Create New Order" API parameters that plug into the relevant fields on the user interface.

Confirm your transaction

Table 1. The Fields Used to Create An Order (see the above curl request for an example).

Field Description Format
matcher_country The country of the country your customer is sending to String (e.g., US)
matcher_currency The currency of the country your customer is sending to String (e.g., USD)
matcher_amount The amount the poster's beneficiary will receive. Number (e.g., 200.00)
exchange_rate Exchange rate String (e.g., 375)
poster_username Your customer's username (the poster) String, a valid email
poster_recipient_username Your customer's beneficiary (the poster's beneficiary) String, a valid email & Kaoshi account
poster_currency Your customer's currency String (e.g., NGN)
poster_country Your customer's country code String (e.g., NG)
poster_amount Amount being sent. Calculate by matcher_amount* exchange_rate Number
poster_payment_method_type The method you will use to make final payment in your customer's country String (e.g., nigerian_bank_payment)
external_order.current_account_balance This is the balance of the bank customer just before the offer was posted Number
external_order.transaction_fee This is the fee charged by the bank to their customer Number
external_order.transaction_fee_currency This is the currency of the fee charged by the bank to their customer String

The response will be an order object. The id field in the order object refers to the Order ID, which is the same as the Transaction ID. An Order ID looks like this: tx-yzngxo3gox.

TIP

In the sandbox environment, after creating an order, our auto-matcher bot will run and automatically match the order. (This should happen every 5 minutes. If it doesn't the bot is sleeping. Please conact support for help)

In the live environment, a user in the diaspora will match the order.

The bank is responsible for completing the poster's transaction by sending a payment to the matcher's beneficiary.

An example order object is below.

You'll need the order id in the next step. It's in the id field of the response below and looks like this: tx-yzngxo3gox

{
    "user_id": "mdzzmd",
    "poster_fee": 123.12,
    "poster_amount": 180750,
    "poster_currency": "NGN",
    "poster_country": "NG",
    "poster_payment_method_type": "nigerian_bank_payment",
    "posters_beneficiary_user_id": "8emvek",
    "matcher_amount": 500,
    "matcher_currency": "USD",
    "matcher_country": "US",
    "matcher_payment_method_type": "zelle_payment",
    "exchange_rate": 361.5,
    "is_matched": 0,
    "is_confirmed": 0,
    "is_completed": 0,
    "is_accepted": 0,
    "updated_at": "2020-09-02T14:35:16.000Z",
    "posted_at": "2020-09-02T14:35:16.000Z",
    "id": "tx-4w9gl33g2x",
    "expires_at": "2020-10-03T00:00:00.000Z",
    "parent_id": null,
    "match_id": null,
    "notified_is_about_to_expire_at": null,
    "published_at": null,
    "is_cancelled": 0,
    "confirmed_at": null,
    "matched_at": null,
    "completed_at": null,
    "cancelled_at": null,
    "matcher_payment_completed_at": null,
    "probably_paid": null,
    "user": {
        "id": "mdzzmd",
        "email": "joy-nigeria-sender@example.com",
        "username": "joy-nigeria-sender@example.com",
        "firstname": "Joy",
        "middlename": null,
        "lastname": "Nigeria-Sender",
        "phone": null,
        "tfa_required_for_login": null,
        "two_factor_verified": null,
        "avatar": null,
        "building_number": null,
        "street_number": null,
        "address": "123 Main St",
        "address2": null,
        "role": "customer",
        "country": "Nigeria",
        "country_abbreviation": "NG",
        "timezone": null,
        "joined_at": "2020-02-24T20:55:11.000Z",
        "updated_at": "2020-02-24T20:55:11.000Z",
        "verified_at": null,
        "verification_started_at": null,
        "email_verified_at": null,
        "name_verified_at": null,
        "dob_verified_at": null,
        "is_active": 1,
        "dob": "1970-01-01T00:00:00.000Z",
        "gender": "female",
        "city": "Lagos",
        "state": "Lagos",
        "zipcode": null,
        "mxuid": null,
        "can_post_offers": 1,
        "can_accept_offers": 0,
        "identity_verified_at": null,
        "hear_from": "Kaoshi",
        "externalUser": {
            "id": 7,
            "created_by": "7dkwdw",
            "user_id": "mdzzmd",
            "username": "joy-nigeria-sender@example.com",
            "bvn": "bvn",
            "created_at": "2020-02-24T20:55:11.000Z",
            "updated_at": "2020-02-24T20:55:11.000Z",
            "createdBy": {
                "id": "7dkwdw",
                "email": "bank-api@example.com",
                "username": "bank-api",
                "firstname": "bank",
                "middlename": null,
                "lastname": "api-lastname",
                "phone": null,
                "tfa_required_for_login": null,
                "two_factor_verified": null,
                "avatar": null,
                "building_number": "HQ 10#",
                "street_number": "21",
                "address": "Araromi St",
                "address2": null,
                "role": "customer",
                "country": "Nigeria",
                "country_abbreviation": "NG",
                "timezone": "Africa/Lagos",
                "joined_at": "2020-07-09T19:41:44.000Z",
                "updated_at": null,
                "verified_at": "2020-07-09T19:41:44.000Z",
                "verification_started_at": null,
                "email_verified_at": "2020-07-09T19:41:44.000Z",
                "name_verified_at": null,
                "dob_verified_at": null,
                "is_active": 1,
                "dob": "1993-01-26T00:00:00.000Z",
                "gender": null,
                "city": "Lagos",
                "state": "Lagos",
                "zipcode": "100001",
                "mxuid": null,
                "can_post_offers": 1,
                "can_accept_offers": 1,
                "identity_verified_at": null,
                "hear_from": "Kaoshi",
                "userOptions": [],
                "has_valid_address": true,
                "currencies": [
                    {
                        "currency_code": "NGN",
                        "currency_name": "nigerian naira",
                        "symbol": "₦",
                        "flag": "ngn.svg",
                        "max_amount": 300000,
                        "min_amount": 30000,
                        "steps": 1000,
                        "payment_types": {
                            "nigerian_bank_payment": {
                                "account_name": "",
                                "account_number": "",
                                "bank_code": ""
                            }
                        },
                        "can_trade_with": [
                            "ghs",
                            "eur",
                            "cad",
                            "gbp",
                            "usd"
                        ]
                    }
                ],
                "bank_options": null
            }
        },
        "userOptions": [],
        "has_valid_address": false,
        "currencies": [
            {
                "currency_code": "NGN",
                "currency_name": "nigerian naira",
                "symbol": "₦",
                "flag": "ngn.svg",
                "max_amount": 300000,
                "min_amount": 30000,
                "steps": 1000,
                "payment_types": {
                    "nigerian_bank_payment": {
                        "account_name": "",
                        "account_number": "",
                        "bank_code": ""
                    }
                },
                "can_trade_with": [
                    "ghs",
                    "eur",
                    "cad",
                    "gbp",
                    "usd"
                ]
            }
        ],
        "bank_options": null
    },
    "confirmedMatches": [],
    "extraOrderDetails": [],
    "postersBeneficiary": {
        "id": "8emvek",
        "email": "janeth-usa-receiver@example.com",
        "username": "janeth-usa-receiver@example.com",
        "firstname": "Janeth",
        "middlename": null,
        "lastname": "USA-Receiver-lastname",
        "phone": null,
        "tfa_required_for_login": null,
        "two_factor_verified": null,
        "avatar": null,
        "building_number": null,
        "street_number": "1501",
        "address": "Broadway",
        "address2": null,
        "role": "customer",
        "country": "United States",
        "country_abbreviation": "US",
        "timezone": "America/New_york",
        "joined_at": "2020-07-09T19:41:44.000Z",
        "updated_at": null,
        "verified_at": "2020-07-09T19:41:44.000Z",
        "verification_started_at": null,
        "email_verified_at": "2020-07-09T19:41:44.000Z",
        "name_verified_at": null,
        "dob_verified_at": null,
        "is_active": 1,
        "dob": "1996-02-29T00:00:00.000Z",
        "gender": null,
        "city": "New York",
        "state": "NY",
        "zipcode": "10036",
        "mxuid": null,
        "can_post_offers": 0,
        "can_accept_offers": 1,
        "identity_verified_at": null,
        "hear_from": "Kaoshi",
        "userOptions": [],
        "has_valid_address": true,
        "currencies": [
            {
                "currency_name": "united states dollar",
                "currency_code": "USD",
                "symbol": "$",
                "flag": "usd.svg",
                "max_amount": 1000,
                "min_amount": 100,
                "steps": 50,
                "payment_types": {
                    "paypal_payment": {
                        "paypal_id": "email_address",
                        "name": "",
                        "phone": ""
                    },
                    "zelle_payment": {
                        "email": "",
                        "phone": "",
                        "name": ""
                    }
                },
                "can_trade_with": [
                    "ngn",
                    "ghs"
                ]
            }
        ],
        "bank_options": null
    },
    "external_order": {
        "id": 1,
        "created_by": "7dkwdw",
        "order_id": "tx-4w9gl33g2x",
        "current_account_balance": 123123.12,
        "transaction_fee": 123.12,
        "transaction_fee_currency": "NGN",
        "created_at": "2020-09-02T14:35:17.000Z",
        "updated_at": "2020-09-02T14:35:17.000Z",
        "createdBy": {
            "id": "7dkwdw",
            "email": "bank-api@example.com",
            "username": "bank-api",
            "firstname": "bank",
            "middlename": null,
            "lastname": "api-lastname",
            "phone": null,
            "tfa_required_for_login": null,
            "two_factor_verified": null,
            "avatar": null,
            "building_number": "HQ 10#",
            "street_number": "21",
            "address": "Araromi St",
            "address2": null,
            "role": "customer",
            "country": "Nigeria",
            "country_abbreviation": "NG",
            "timezone": "Africa/Lagos",
            "joined_at": "2020-07-09T19:41:44.000Z",
            "updated_at": null,
            "verified_at": "2020-07-09T19:41:44.000Z",
            "verification_started_at": null,
            "email_verified_at": "2020-07-09T19:41:44.000Z",
            "name_verified_at": null,
            "dob_verified_at": null,
            "is_active": 1,
            "dob": "1993-01-26T00:00:00.000Z",
            "gender": null,
            "city": "Lagos",
            "state": "Lagos",
            "zipcode": "100001",
            "mxuid": null,
            "can_post_offers": 1,
            "can_accept_offers": 1,
            "identity_verified_at": null,
            "hear_from": "Kaoshi",
            "userOptions": [
                {
                    "id": 1,
                    "user_id": "7dkwdw",
                    "name": "bank-options",
                    "description": null,
                    "value": {
                        "logo": "sterling-bank-logo.png"
                    },
                    "created_at": "2020-07-09T19:41:45.000Z",
                    "updated_at": null
                }
            ],
            "has_valid_address": true,
            "currencies": [
                {
                    "currency_code": "NGN",
                    "currency_name": "nigerian naira",
                    "symbol": "₦",
                    "flag": "ngn.svg",
                    "max_amount": 300000,
                    "min_amount": 30000,
                    "steps": 1000,
                    "payment_types": {
                        "nigerian_bank_payment": {
                            "account_name": "",
                            "account_number": "",
                            "bank_code": ""
                        }
                    },
                    "can_trade_with": [
                        "ghs",
                        "eur",
                        "cad",
                        "gbp",
                        "usd"
                    ]
                }
            ],
            "bank_options": {
                "logo": "sterling-bank-logo.png"
            }
        },
        "bank_logo": "sterling-bank-logo.png"
    },
    "is_processing": 1,
    "can_cancel_order": true,
    "poster_payment_purpose": null,
    "matcher_payment_purpose": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339