3.9 Query parameters
Query parameters to pre-populate fields in our widget with information you have gathered
URL encoding
Query parameters values should be URL encoded to prevent mistakes. For example,
[email protected]should be encoded totest%2Bsomething%40yellowcard.io. Another example of a string with spaces isProceeds from business transactionsbecomesProceeds%20from%20business%20transactions.
| Parameter | Description |
|---|---|
| currencyAmount | The amount in local currency which the customer wants to transact. e.g. 10000 |
| txType | Default tab to open the widget with and disables switching between tabs. buy opens the buy tab and sell opens the sell tab. If a value isn't passed, it defaults to the buy tab. |
| token | The asset to be transacted. If walletAddress or signature parameters are passed through query parameters then this parameter is mandatory and it will be uneditable. Options are USDC, BTC, ETH, USDT. |
| network | Some tokens have multiple networks available, e.g. USDC is available on ERC20 and CELO network.Valid options include ERC20, TRC20, CELO, BTC.If no network is specified, our default network will be assigned to the token. If an invalid network is specified, our default network will be assigned to the token. Supported crypto and network guide is available here |
The email address of the user. This value must be url-encoded. e.g. test%2Bsomething%40yellowcard.io | |
| firstname | The first name(s) of the user. If more than one name is given they should be added to this parameter seperated by a space. If more than one name is given this value should be url-encoded. e.g.James%20Earl |
| lastname | The last name of the user. e.g. Jones |
| day | The day of birth of the user. This number should be passed as a 2-digit string, e.g. 08 |
| month | The month of birth of the user. This number should be passed as a 2-digit string, e.g. 04 |
| year | The year of birth of the user. This number should be a 4-digit string, e.g. 1988 |
| phone | The phone number of the user. This number excludes the country code and should not contain spaces. e.g. 0768940938 |
| street | The street address of the user. This value should be url-encoded. e.g. 56%20Darling%20Street |
| state | The state in which the user resides. This value is from a predefined list, please see this section for options. e.g. Adamawa |
| city | The city in which the user resides. This value is. from a predefined list, please see this section for options. e.g. Gombi |
| postalCode | The postal code of the user's residence. e.g. 8453 |
| sourceOfFunds | Where the user receives funds from to perform this transaction. These values are from a predefined list. Options are Salary, Savings, Proceeds from business transactions, Inheritance, Winnings. If more than one option is passed, it should be passed in seperate query parameters. This value should be url-encoded if there are spaces. e.g. &sourceOfFunds=Salary&sourceOfFunds=Savings&sourceOfFunds=Winnings&sourceOfFunds=Proceeds%20from%20business%20transactions |
| otherSourceOfFunds | Any other potential sources of funds, passed as a string. e.g. Found%20it%20on%20the%20floor |
| walletAddress | The wallet address of the user where the funds will be transferred to. If this value is passed through it will be uneditable in the widget and must be accompanied by token and signature. e.g. TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t |
| channelId | The ID of the Yellowcard channel through which the fiat funds will be deposited. This is akin to payment method, and can be determined by the GET CHANNELS endpoint. e.g. af944f0c-ba70-47c7-86dc-1bad5a6ab4e4 |
| channelType | The type of Yellowcard channel through which the fiat funds will be transferred. Valid values for this field are momo or bank. If no value is supplied then the user will pick their own channel on the relevant widget screen. |
| idType | The type of identification document. Options are NIN Slip/Card, BVN. This value should be url-encoded if it cointains a slash. |
| idNumber | The number on the identification document. e.g. 830348944634563 |
| redirectLink | The url the customer will be directed to upon completion of the transaction. This value should be url-encoded. If it is included, it will overwrite any redirect url specified in the partner config. |
| signature | The sha256 hash to verify the wallet address and token used as query parameters. If walletAddress is passed as a query parameter than this parameter is mandatory. This value should be url-encoded. To see how to generate this signature, see this section. e.g. 6TR5tXV83KktatE3bOI0nBbu2wz4JOdxGZ%2FREe5AwOM%3D |
| sequenceId | The unique ID provided by you that the order will be created with, in order to track it via webhooks or the API. e.g. 7a03dfc8-ccc4-4350-a28f-be038edf3cc4 |
City and State
The city and state parameter should be one of the following combinations in the following mapping, otherwise the drop-downs will not populate correctly.
Nigeria
{
country: Countries.NIGERIA,
cityState: [
{
name: 'Abia',
cities: [
'Aba South',
'Arochukwu',
'Bende',
'Ikwuano',
'Isiala Ngwa North',
'Isiala Ngwa South',
'Isuikwuato',
'Obi Ngwa',
'Ohafia',
'Osisioma',
'Ugwunagbo',
'Ukwa East',
'Ukwa West',
'Umuahia North',
'Umuahia South',
'Umu Nneochi',
],
},
{
name: 'Adamawa',
cities: [
'Fufure',
'Ganye',
'Gayuk',
'Gombi',
'Grie',
'Hong',
'Jada',
'Lamurde',
'Madagali',
'Maiha',
'Mayo Belwa',
'Michika',
'Mubi North',
'Mubi South',
'Numan',
'Shelleng',
'Song',
'Toungo',
'Yola North',
'Yola South',
],
},
{
name: 'Akwa Ibom',
cities: [
'Eastern Obolo',
'Eket',
'Esit Eket',
'Essien Udim',
'Etim Ekpo',
'Etinan',
'Ibeno',
'Ibesikpo Asutan',
'Ibiono-Ibom',
'Ika',
'Ikono',
'Ikot Abasi',
'Ikot Ekpene',
'Ini',
'Itu',
'Mbo',
'Mkpat-Enin',
'Nsit-Atai',
'Nsit-Ibom',
'Nsit-Ubium',
'Obot Akara',
'Okobo',
'Onna',
'Oron',
'Oruk Anam',
'Udung-Uko',
'Ukanafun',
'Uruan',
'Urue-Offong/Oruko',
'Uyo',
],
},
{
name: 'Anambra',
cities: [
'Anambra East',
'Anambra West',
'Anaocha',
'Awka North',
'Awka South',
'Ayamelum',
'Dunukofia',
'Ekwusigo',
'Idemili North',
'Idemili South',
'Ihiala',
'Njikoka',
'Nnewi North',
'Nnewi South',
'Ogbaru',
'Onitsha North',
'Onitsha South',
'Orumba North',
'Orumba South',
'Oyi',
],
},
{
name: 'Bauchi',
cities: [
'Bauchi',
'Bogoro',
'Damban',
'Darazo',
'Dass',
'Gamawa',
'Ganjuwa',
'Giade',
'Itas/Gadau',
"Jama'are",
'Katagum',
'Kirfi',
'Misau',
'Ningi',
'Shira',
'Tafawa Balewa',
'Toro',
'Warji',
'Zaki',
],
},
{
name: 'Bayelsa',
cities: [
'Ekeremor',
'Kolokuma/Opokuma',
'Nembe',
'Ogbia',
'Sagbama',
'Southern Ijaw',
'Yenagoa',
],
},
{
name: 'Benue',
cities: [
'Apa',
'Ado',
'Buruku',
'Gboko',
'Guma',
'Gwer East',
'Gwer West',
'Katsina-Ala',
'Konshisha',
'Kwande',
'Logo',
'Makurdi',
'Obi',
'Ogbadibo',
'Ohimini',
'Oju',
'Okpokwu',
'Oturkpo',
'Tarka',
'Ukum',
'Ushongo',
'Vandeikya',
],
},
{
name: 'Borno',
cities: [
'Askira/Uba',
'Bama',
'Bayo',
'Biu',
'Chibok',
'Damboa',
'Dikwa',
'Gubio',
'Guzamala',
'Gwoza',
'Hawul',
'Jere',
'Kaga',
'Kala/Balge',
'Konduga',
'Kukawa',
'Kwaya Kusar',
'Mafa',
'Magumeri',
'Maiduguri',
'Marte',
'Mobbar',
'Monguno',
'Ngala',
'Nganzai',
'Shani',
],
},
{
name: 'Cross River',
cities: [
'Akamkpa',
'Akpabuyo',
'Bakassi',
'Bekwarra',
'Biase',
'Boki',
'Calabar Municipal',
'Calabar South',
'Etung',
'Ikom',
'Obanliku',
'Obubra',
'Obudu',
'Odukpani',
'Ogoja',
'Yakuur',
'Yala',
],
},
{
name: 'Delta',
cities: [
'Aniocha South',
'Bomadi',
'Burutu',
'Ethiope East',
'Ethiope West',
'Ika North East',
'Ika South',
'Isoko North',
'Isoko South',
'Ndokwa East',
'Ndokwa West',
'Okpe',
'Oshimili North',
'Oshimili South',
'Patani',
'Sapele',
'Udu',
'Ughelli North',
'Ughelli South',
'Ukwuani',
'Uvwie',
'Warri North',
'Warri South',
'Warri South West',
],
},
{
name: 'Ebonyi',
cities: [
'Afikpo North',
'Afikpo South',
'Ebonyi',
'Ezza North',
'Ezza South',
'Ikwo',
'Ishielu',
'Ivo',
'Izzi',
'Ohaozara',
'Ohaukwu',
'Onicha',
],
},
{
name: 'Edo',
cities: [
'Egor',
'Esan Central',
'Esan North-East',
'Esan South-East',
'Esan West',
'Etsako Central',
'Etsako East',
'Etsako West',
'Igueben',
'Ikpoba Okha',
'Orhionmwon',
'Oredo',
'Ovia North-East',
'Ovia South-West',
'Owan East',
'Owan West',
'Uhunmwonde',
],
},
{
name: 'Ekiti',
cities: [
'Efon',
'Ekiti East',
'Ekiti South-West',
'Ekiti West',
'Emure',
'Gbonyin',
'Ido Osi',
'Ijero',
'Ikere',
'Ikole',
'Ilejemeje',
'Irepodun/Ifelodun',
'Ise/Orun',
'Moba',
'Oye',
],
},
{
name: 'Enugu',
cities: [
'Awgu',
'Enugu East',
'Enugu North',
'Enugu South',
'Ezeagu',
'Igbo Etiti',
'Igbo Eze North',
'Igbo Eze South',
'Isi Uzo',
'Nkanu East',
'Nkanu West',
'Nsukka',
'Oji River',
'Udenu',
'Udi',
'Uzo Uwani',
],
},
{
name: 'FCT',
cities: [
'Bwari',
'Gwagwalada',
'Kuje',
'Kwali',
'Municipal Area Council',
],
},
{
name: 'Gombe',
cities: [
'Balanga',
'Billiri',
'Dukku',
'Funakaye',
'Gombe',
'Kaltungo',
'Kwami',
'Nafada',
'Shongom',
'Yamaltu/Deba',
],
},
{
name: 'Imo',
cities: [
'Ahiazu Mbaise',
'Ehime Mbano',
'Ezinihitte',
'Ideato North',
'Ideato South',
'Ihitte/Uboma',
'Ikeduru',
'Isiala Mbano',
'Isu',
'Mbaitoli',
'Ngor Okpala',
'Njaba',
'Nkwerre',
'Nwangele',
'Obowo',
'Oguta',
'Ohaji/Egbema',
'Okigwe',
'Orlu',
'Orsu',
'Oru East',
'Oru West',
'Owerri Municipal',
'Owerri North',
'Owerri West',
'Unuimo',
],
},
{
name: 'Jigawa',
cities: [
'Babura',
'Biriniwa',
'Birnin Kudu',
'Buji',
'Dutse',
'Gagarawa',
'Garki',
'Gumel',
'Guri',
'Gwaram',
'Gwiwa',
'Hadejia',
'Jahun',
'Kafin Hausa',
'Kazaure',
'Kiri Kasama',
'Kiyawa',
'Kaugama',
'Maigatari',
'Malam Madori',
'Miga',
'Ringim',
'Roni',
'Sule Tankarkar',
'Taura',
'Yankwashi',
],
},
{
name: 'Kaduna',
cities: [
'Chikun',
'Giwa',
'Igabi',
'Ikara',
'Jaba',
"Jema'a",
'Kachia',
'Kaduna North',
'Kaduna South',
'Kagarko',
'Kajuru',
'Kaura',
'Kauru',
'Kubau',
'Kudan',
'Lere',
'Makarfi',
'Sabon Gari',
'Sanga',
'Soba',
'Zangon Kataf',
'Zaria',
],
},
{
name: 'Kano',
cities: [
'Albasu',
'Bagwai',
'Bebeji',
'Bichi',
'Bunkure',
'Dala',
'Dambatta',
'Dawakin Kudu',
'Dawakin Tofa',
'Doguwa',
'Fagge',
'Gabasawa',
'Garko',
'Garun Mallam',
'Gaya',
'Gezawa',
'Gwale',
'Gwarzo',
'Kabo',
'Kano Municipal',
'Karaye',
'Kibiya',
'Kiru',
'Kumbotso',
'Kunchi',
'Kura',
'Madobi',
'Makoda',
'Minjibir',
'Nasarawa',
'Rano',
'Rimin Gado',
'Rogo',
'Shanono',
'Sumaila',
'Takai',
'Tarauni',
'Tofa',
'Tsanyawa',
'Tudun Wada',
'Ungogo',
'Warawa',
'Wudil',
],
},
{
name: 'Katsina',
cities: [
'Batagarawa',
'Batsari',
'Baure',
'Bindawa',
'Charanchi',
'Dandume',
'Danja',
'Dan Musa',
'Daura',
'Dutsi',
'Dutsin Ma',
'Faskari',
'Funtua',
'Ingawa',
'Jibia',
'Kafur',
'Kaita',
'Kankara',
'Kankia',
'Katsina',
'Kurfi',
'Kusada',
"Mai'Adua",
'Malumfashi',
'Mani',
'Mashi',
'Matazu',
'Musawa',
'Rimi',
'Sabuwa',
'Safana',
'Sandamu',
'Zango',
],
},
{
name: 'Kebbi',
cities: [
'Arewa Dandi',
'Argungu',
'Augie',
'Bagudo',
'Birnin Kebbi',
'Bunza',
'Dandi',
'Fakai',
'Gwandu',
'Jega',
'Kalgo',
'Koko/Besse',
'Maiyama',
'Ngaski',
'Sakaba',
'Shanga',
'Suru',
'Wasagu/Danko',
'Yauri',
'Zuru',
],
},
{
name: 'Kogi',
cities: [
'Ajaokuta',
'Ankpa',
'Bassa',
'Dekina',
'Ibaji',
'Idah',
'Igalamela Odolu',
'Ijumu',
'Kabba/Bunu',
'Kogi',
'Lokoja',
'Mopa Muro',
'Ofu',
'Ogori/Magongo',
'Okehi',
'Okene',
'Olamaboro',
'Omala',
'Yagba East',
'Yagba West',
],
},
{
name: 'Kwara',
cities: [
'Baruten',
'Edu',
'Ekiti',
'Ifelodun',
'Ilorin East',
'Ilorin South',
'Ilorin West',
'Irepodun',
'Isin',
'Kaiama',
'Moro',
'Offa',
'Oke Ero',
'Oyun',
'Pategi',
],
},
{
name: 'Lagos',
cities: [
'Ajeromi-Ifelodun',
'Alimosho',
'Amuwo-Odofin',
'Apapa',
'Badagry',
'Epe',
'Eti Osa',
'Ibeju-Lekki',
'Ifako-Ijaiye',
'Ikeja',
'Ikorodu',
'Kosofe',
'Lagos Island',
'Lagos Mainland',
'Mushin',
'Ojo',
'Oshodi-Isolo',
'Shomolu',
'Surulere',
],
},
{
name: 'Nasarawa',
cities: [
'Awe',
'Doma',
'Karu',
'Keana',
'Keffi',
'Kokona',
'Lafia',
'Nasarawa',
'Nasarawa Egon',
'Obi',
'Toto',
'Wamba',
],
},
{
name: 'Niger',
cities: [
'Agwara',
'Bida',
'Borgu',
'Bosso',
'Chanchaga',
'Edati',
'Gbako',
'Gurara',
'Katcha',
'Kontagora',
'Lapai',
'Lavun',
'Magama',
'Mariga',
'Mashegu',
'Mokwa',
'Moya',
'Paikoro',
'Rafi',
'Rijau',
'Shiroro',
'Suleja',
'Tafa',
'Wushishi',
],
},
{
name: 'Ogun',
cities: [
'Abeokuta South',
'Ado-Odo/Ota',
'Egbado North',
'Egbado South',
'Ewekoro',
'Ifo',
'Ijebu East',
'Ijebu North',
'Ijebu North East',
'Ijebu Ode',
'Ikenne',
'Imeko Afon',
'Ipokia',
'Obafemi Owode',
'Odeda',
'Odogbolu',
'Ogun Waterside',
'Remo North',
'Shagamu',
],
},
{
name: 'Ondo',
cities: [
'Akoko North-West',
'Akoko South-West',
'Akoko South-East',
'Akure North',
'Akure South',
'Ese Odo',
'Idanre',
'Ifedore',
'Ilaje',
'Ile Oluji/Okeigbo',
'Irele',
'Odigbo',
'Okitipupa',
'Ondo East',
'Ondo West',
'Ose',
'Owo',
],
},
{
name: 'Osun',
cities: [
'Atakunmosa West',
'Aiyedaade',
'Aiyedire',
'Boluwaduro',
'Boripe',
'Ede North',
'Ede South',
'Ife Central',
'Ife East',
'Ife North',
'Ife South',
'Egbedore',
'Ejigbo',
'Ifedayo',
'Ifelodun',
'Ila',
'Ilesa East',
'Ilesa West',
'Irepodun',
'Irewole',
'Isokan',
'Iwo',
'Obokun',
'Odo Otin',
'Ola Oluwa',
'Olorunda',
'Oriade',
'Orolu',
'Osogbo',
],
},
{
name: 'Oyo',
cities: [
'Akinyele',
'Atiba',
'Atisbo',
'Egbeda',
'Ibadan North',
'Ibadan North-East',
'Ibadan North-West',
'Ibadan South-East',
'Ibadan South-West',
'Ibarapa Central',
'Ibarapa East',
'Ibarapa North',
'Ido',
'Irepo',
'Iseyin',
'Itesiwaju',
'Iwajowa',
'Kajola',
'Lagelu',
'Ogbomosho North',
'Ogbomosho South',
'Ogo Oluwa',
'Olorunsogo',
'Oluyole',
'Ona Ara',
'Orelope',
'Ori Ire',
'Oyo',
'Oyo East',
'Saki East',
'Saki West',
'Surulere',
],
},
{
name: 'Plateau',
cities: [
'Barkin Ladi',
'Bassa',
'Jos East',
'Jos North',
'Jos South',
'Kanam',
'Kanke',
'Langtang South',
'Langtang North',
'Mangu',
'Mikang',
'Pankshin',
"Qua'an Pan",
'Riyom',
'Shendam',
'Wase',
],
},
{
name: 'Rivers',
cities: [
'Ahoada East',
'Ahoada West',
'Akuku-Toru',
'Andoni',
'Asari-Toru',
'Bonny',
'Degema',
'Eleme',
'Emuoha',
'Etche',
'Gokana',
'Ikwerre',
'Khana',
'Obio/Akpor',
'Ogba/Egbema/Ndoni',
'Ogu/Bolo',
'Okrika',
'Omuma',
'Opobo/Nkoro',
'Oyigbo',
'Port Harcourt',
'Tai',
],
},
{
name: 'Sokoto',
cities: [
'Bodinga',
'Dange Shuni',
'Gada',
'Goronyo',
'Gudu',
'Gwadabawa',
'Illela',
'Isa',
'Kebbe',
'Kware',
'Rabah',
'Sabon Birni',
'Shagari',
'Silame',
'Sokoto North',
'Sokoto South',
'Tambuwal',
'Tangaza',
'Tureta',
'Wamako',
'Wurno',
'Yabo',
],
},
{
name: 'Taraba',
cities: [
'Bali',
'Donga',
'Gashaka',
'Gassol',
'Ibi',
'Jalingo',
'Karim Lamido',
'Kumi',
'Lau',
'Sardauna',
'Takum',
'Ussa',
'Wukari',
'Yorro',
'Zing',
],
},
{
name: 'Yobe',
cities: [
'Bursari',
'Damaturu',
'Fika',
'Fune',
'Geidam',
'Gujba',
'Gulani',
'Jakusko',
'Karasuwa',
'Machina',
'Nangere',
'Nguru',
'Potiskum',
'Tarmuwa',
'Yunusari',
'Yusufari',
],
},
{
name: 'Zamfara',
cities: [
'Bakura',
'Birnin Magaji/Kiyaw',
'Bukkuyum',
'Bungudu',
'Gummi',
'Gusau',
'Kaura Namoda',
'Maradun',
'Maru',
'Shinkafi',
'Talata Mafara',
'Chafe',
'Zurmi',
],
},
],
},
];
Signing order requests
Signing the order request
If the
walletAddressis supplied via query parameters, thentokenandsignatureare mandatory to supply as well, and will be uneditable by the customer. Conversely, if asignatureis supplied, then both thetokenand thewalletAddressparameters are also mandatory and will be uneditable by the customer. Thetokenparameter may, however, be used on it's own without awalletAddressand asignatureand will then remain editable.The signature should be url-encoded.
The HMAC signature can be generated as a sha256 hash of stringified JSON body computed from your secret key. The JSON body takes the form:
{
address: "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
token: "USDT"
}
The following is some sample code that shows how to compute the value for signature.
const crypto = require('crypto');
const walletAddress = "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"
const token = 'USDT'
const message = {
address: walletAddress,
token: token,
}
const secretKey = '8a2bfda7f762403b97a3abddc9c16c9298d066f81b7d01679c918929528f969c'
const signature = crypto
.createHmac('sha256', secretKey)
.update(JSON.stringify(message))
.digest('base64');
console.log(signature)
The value should be url-encoded.
Optional Skipping of Pages
Certain widget buy/sell pages can be skipped if the required query params are passed through correctly.
Skipping the first page
The initial transaction page can be skipped by passing through the following:
- For a buy transaction correctly set:
- txType=buy
- currencyAmount
- token
- For a sell transaction correctly set:
- txType=sell
- cryptoAmount
- token
Skipping the channel selection page
The channel selection page can be skipped if either of the following parameters are correctly set:
- channelId
- channelType
Updated 1 day ago