3.9 Query parameters
Query parameters to pre-populate fields in our widget with information you have gathered
URL encodingQuery 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 |
cryptoAmount | The amount of |
txType | Default tab to open the widget with and disables switching between tabs. |
token | The asset to be transacted. If this is passed in, then the token dropdown is uneditable. Options are |
walletAddress | The address to be used in a widget buy transaction. If this field is provided, then it is expected that the token and signature fields are also provided else the widget is not going to load properly. If this field is provided, then the address field is populated and uneditable. |
localCurrency | The local currency to select when the widget is loaded. If this parameter is passed, the field will not be editable for currencies that are neither |
country | The 2-letter country code signifying the country for the currency to be selected. This only takes effect when the |
network | Some tokens have multiple networks available, e.g. |
The email address of the user. This value must be url-encoded. e.g. | |
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. |
lastname | The last name of the user. e.g. |
day | The day of birth of the user. This number should be passed as a 2-digit string, e.g. |
month | The month of birth of the user. This number should be passed as a 2-digit string, e.g. |
year | The year of birth of the user. This number should be a 4-digit string, e.g. |
phone | The phone number of the user. This number excludes the country code and should not contain spaces. e.g. |
street | The street address of the user. This value should be url-encoded. e.g. |
state | The state in which the user resides. This value is from a predefined list, please see this section for options. e.g. |
city | The city in which the user resides. This value is. from a predefined list, please see this section for options. e.g. |
postalCode | The postal code of the user's residence. e.g. |
sourceOfFunds | Where the user receives funds from to perform this transaction. These values are from a predefined list. Options are |
otherSourceOfFunds | Any other potential sources of funds, passed as a string. e.g. |
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 |
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. |
channelType | The type of Yellowcard channel through which the fiat funds will be transferred. Valid values for this field are |
idType | The type of identification document. This value should be url-encoded if it cointains a slash. |
idNumber | The number on the identification document. e.g. |
additionalIdType | The type of identification document when an additional ID is required. In the case of Nigeria this would be BVN. |
additionalIdNumber | The number on the identification document, in the case of Nigeria this would be the BVN number of the customer. |
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- |
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. This should be a valid url with https: protocol. |
redirectLinkSignature | The Note: If the redirectLink is to be used after a sell transaction, then the To see how to generate this signature, see this section . e.g. |
Multi-country currency support
For currencies shared between multiple countries (XAF and XOF), the widget has some specific requirements.
- If the
localCurrencyparam is passed as one of these currencies, then the currency is selected when the widget is loaded as long as the partner has a rate for one of those currencies enabled. However, the currency can be modified by the customer. - If the
localCurrencyis passed and thecountryis passed as well, then the correct currency for the specified country is selected as long as the partner has a rate for the currency-country combination. Note that the currency cannot be changed by the customer in this scenario.
IdType and AdditionalIdType - Nigeria
For KYC in Nigeria, both NIN and BVN numbers are required. To pass these as query parameters, follow this convention:
- idType = NIN Slip/Card, idNumber = customer_nin_number
- additionalIdNumber = BVN, additionalIdNumber = customer_bvn_number
Note: idType above needs to be url-encoded
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 requestIf 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(encodeURIComponent(signature))The value should be url-encoded (using javascriptencodeURIComponent function)
Signing redirect links
Signing the redirectLinkIf the
redirectLinkis supplied via query parameters, thenredirectLinkSignatureis mandatory to supply as well.The redirectLinkSignature 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:
{
redirectLink: "https://www.yellowcard.io"
}The following is some sample code that shows how to compute the value for redirectLinkSignature.
const crypto = require('crypto');
const redirectLink = "https://www.yellowcard.io"
const message = {
redirectLink: redirectLink,
}
const secretKey = '8a2bfda7f762403b97a3abddc9c16c9298d066f81b7d01679c918929528f969c'
const signature = crypto
.createHmac('sha256', secretKey)
.update(JSON.stringify(message))
.digest('base64');
console.log(encodeURIComponent(signature))The value should be url-encoded (using javascriptencodeURIComponent function)
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 7 months ago