To use APIs successfully, developers and businesses need to know how to integrate with them<\/a>. Every API comes with API documentation outlining when and how an API is used. Such documentation often includes the term API call.<\/p>\n\n\n\n Find out what API calls are and how to use them.<\/p>\n\n\n\n An API call (also called an API request) is how a client application and an API endpoint<\/a> (the point of access to a server or program) communicate.<\/p>\n\n\n\n Every API call is initiated by the client application. The process consists of the following steps:<\/p>\n\n\n\n API calls can be made using virtually any programming language as long as it is supported by the API.<\/p>\n\n\n\n The two basic ways to make an API call are:<\/p>\n\n\n\n In both cases, APIs communicate with client applications using the HTTP protocol, meaning they utilize the five basic HTTP functions, which are:<\/p>\n\n\n\n REST APIs return a value for all functions while SOAP APIs only respond to POST. However, API owners reserve the right to prevent the API from responding to certain types of requests.<\/p>\n\n\n\n Modern day APIs are used to access, manage, and manipulate vast amounts of data, calling for more complex API calls.<\/p>\n\n\n\n Complex API calls are achieved through established API-building protocols, patterns, and best practices. Some of the most popular API protocols are:<\/p>\n\n\n\n The structure of an API call depends on the API type<\/a>, architectural style, and communication protocol. API providers maintain documentation that explains how to structure an API call and lists resource locations (URL endpoints) for their service.<\/p>\n\n\n\n For example, RESTful API calls using the HTTP protocol consist of 5 elements:<\/p>\n\n\n\n The following steps illustrate what actions a client needs to take when making an API call.<\/p>\n\n\n\n API providers want to protect server resources by authenticating API calls before authorizing a request. Non-essential server resources are often protected using Basic Auth<\/a>; however, APIs that exchange sensitive customer information use bearer tokens and the OAuth 2.0<\/a> standard to authenticate API calls.<\/p>\n\n\n\n To authenticate API calls:<\/p>\n\n\n\n Endpoint URLs tell API users where to send the API calls.<\/p>\n\n\n\n API providers try to define and group endpoints to reflect the logical structure of server resources. Usually, an API service shares the same base URL, while the endpoint URI varies for each resource.<\/p>\n\n\n\n For example, CCBill\u2019s RESTful Transaction API uses distinct endpoints for different actions a client can initiate with their API calls.<\/p>\n\n\n\n The CCBill RESTful API base URL is https:\/\/api.ccbill.com<\/strong>.<\/p>\n\n\n\n The endpoint URL for generating a payment token uses the \/payment-tokens<\/strong> resource:<\/p>\n\n\n\n https:\/\/api.ccbill.com\/payment-tokens\/merchant-only<\/strong><\/em><\/p>\n\n\n\n If a merchant wants to verify the customer\u2019s identity before creating a payment token (by requesting a CVV2 code<\/a>), they need to use a different endpoint:<\/p>\n\n\n\n https:\/\/api.ccbill.com\/payment-tokens\/merchant-only-verify<\/strong><\/em><\/p>\n\n\n\n The created token is then passed to a third endpoint in a transaction request:<\/p>\n\n\n\n https:\/\/api.ccbill.com\/transactions\/payment-tokens\/{payment_token_id}<\/strong><\/em><\/p>\n\n\n\n This endpoint enables merchants to bill a customer<\/a>.<\/p>\n\n\n\n Merchants need to identify which endpoint provides the services they need and follow the documentation to the letter for this process to be successful.<\/p>\n\n\n\n An API header contains API call metadata like acceptable media types and authorization information. For example, CCBill requires merchants to provide their bearer token in the request header before authorizing an API request:<\/p>\n\n\n\n The header array in this PHP example prevents client-side caching. It also requires objects to follow the JSON (JavaScript Object Notation) open-standard file format and use the application\/json<\/strong> content type.<\/p>\n\n\n\n The body of an API call contains a set of parameters and their corresponding values. The API documentation must list every parameter for each endpoint. It should also provide parameter descriptions, what data types are acceptable, and emphasize if a parameter is required or optional.<\/p>\n\n\n\n Let\u2019s explore parameters and their values using the same API call example as above:<\/p>\n\n\n\n CCBill\u2019s system verifies the request and uses the provided customer information to create a payment token.<\/p>\n\n\n\n Before adding parameters to a call, always consult the appropriate API documentation for instructions.<\/p>\n\n\n\n The API server responds by sending structured parameters and their corresponding values based on the API request. A common component of API server responses are HTTP status codes.<\/strong> HTTP codes confirm if a request was successful or inform API clients that a request failed.<\/p>\n\n\n\n For example, successfully creating a payment token using CCBill\u2019s RESTful API returns a 200 HTTP code and the following parameters:<\/p>\n\n\n\n Merchants can extract the paymentTokenID<\/em> string and make a new API call to charge the customer.<\/p>\n\n\n\n Unsuccessful API calls always return a status code, upon which the user or client can determine what went wrong.<\/p>\n\n\n\n Here are some of the most used HTTP status codes and their meanings.<\/p>\n\n\n\n 1xx HTTP codes are temporary status codes that inform the client that their request has been received and waiting to be processed.<\/p>\n\n\n\n The following table explains some of the most used 1xx codes:<\/p>\n\n\n\n![\"What](\"https:\/\/ccbill.com\/kb\/wp-content\/uploads\/2022\/09\/what-is-an-api-call.png\")
<\/figure>\n\n\n\nWhat is an API Call?<\/h2>\n\n\n\n
\n
\n
\n
![\"HTTP](\"https:\/\/ccbill.com\/kb\/wp-content\/uploads\/2022\/09\/api-call-http-methods.jpg\")
<\/figure>\n\n\n\nAPI Calls and Their Relationship with API Protocols<\/h3>\n\n\n\n
\n
How to Make an API Call<\/h2>\n\n\n\n
\n
Step 1: Authentication and Authorization<\/h3>\n\n\n\n
\n
Step 2: Identify API Endpoints<\/h3>\n\n\n\n
Step 3: API Call Header<\/h3>\n\n\n\n
<?php\n$request = new HttpRequest();\n$request->setUrl('https:\/\/api.ccbill.com\/payment-tokens\/merchant-only-verify');\n$request->setMethod(HTTP_METH_POST);\n\/\/Headers begin here\n$request->setHeaders(array(\n'Cache-Control' => 'no-cache',\n'Authorization' => 'Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsibWNuLXRyYW5zYWN0aW9uLXNlcnZpY2UiLCJtY24tYWRtaW4tc2VydmljZSJdLCJzY29wZSI6WyJjcmVhdGVfdG9rZW4iLCJyZWFkX3Rva2VuIiwiY2hhcmdlX3Rva2VuIiwiY3JlYXRlX3Byb2dyYW0iLCJyZWFkX3Byb2dyYW0iLCJjcmVhdGVfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIiwicmVhZF9wcm9ncmFtX3BhcnRpY2lwYXRpb24iLCJtb2RpZnlfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIl0sImV4cCI6MTUzNzM4MDczNiwiYXV0aG9yaXRpZXMiOlsiTUNOX0FQSV9UT0tFTl9DSEFSR0VSIiwiTUNOX0FQSV9UT0tFTl9DUkVBVE9SIiwiTUNOX0FQSV9BRE1JTiJdLCJqdGkiOiI4YzI2Njg1MC00NjMzLTQzZDMtYjZjOC1lNzIyY2ExNjQ1YTUiLCJjbGllbnRfaWQiOiI1MjE3NjhhYTc1OGQxMWU4YWE2YjAwNTA1NjlkMTU4NSJ9.HRYXZFATkIcI2_LJ1W_xo67IfBnbN9atyYNzyHqseLxYUxzgwBsAV5rNqCixKemOrDIeQLBN4jrwRsBIHDpEvshwBC8XmTodDJzpGmMaU9s1r20RV68X0_d1yTgSDke_Of7VCrVmJRbSuDl7AgsfTqQ1J7nWyu9vcIaER93ms-vadser_Ot9Z68_HAmCJL3DCLpdIFq3PYtBMKKKqXbvhfhSZQZD3b6-aewAnBo0VzpvK6tREqw1rv9_73oAvYcW2aHAj79ILr8viWMM40LyDKMMYOYkneg3hJUQsUVeh9WzztYUJKzERYNXje9fYIGN-eofoLvX7OZJ3eXmIfkrfQ',\n'Content-Type' => 'application\/json'\n));\n\/\/ Headers end here\n$request->setBody('{ "clientAccnum": 900000, "clientSubacc": 0, "customerInfo": { "customerFname": "Tyler", "customerLname": "Thomas", "address1": "Woodland Drive", "address2": "Apt 21", "city": "Tempe", "state": "AZ", "zipcode": "85281", "country": "US", "phoneNumber": "5555555555", "email": "tthomas@xyz.com", "ipAddress": "10.70.60.14", "browserHttpUserAgent": "Mozilla\/5.0 (Windows NT 6.1; Win64; x64; rv:60.0) Gecko\/20100101 Firefox\/60.0", "browserHttpAccept": "text\/html,application\/xhtml+xml,application\/xml;q=0.9,*\/*;q=0.8", "browserHttpAcceptLanguage": "en-US,en;q=0.5", "browserHttpAcceptEncoding": "gzip, deflate, br" }, "paymentInfo": { "creditCardPaymentInfo": { "cardNum": "4473707989493598", "nameOnCard": "Tyler Thomas", "expMonth": "04", "expYear": "2019", "cvv2": "123" } }, "subscriptionId":900000000000000001, "timeToLive": 30, "validNumberOfUse": 3 }');\ntry {\n$response = $request->send();\necho $response->getBody();\n} catch (HttpException $ex) {\necho $ex;\n}\n?><\/code><\/pre>\n\n\n\nStep 4: API Call Parameters<\/h3>\n\n\n\n
<?php\n$request = new HttpRequest();\n$request->setUrl('https:\/\/api.ccbill.com\/payment-tokens\/merchant-only-verify');\n$request->setMethod(HTTP_METH_POST);\n$request->setHeaders(array(\n'Cache-Control' => 'no-cache',\n'Authorization' => 'Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsibWNuLXRyYW5zYWN0aW9uLXNlcnZpY2UiLCJtY24tYWRtaW4tc2VydmljZSJdLCJzY29wZSI6WyJjcmVhdGVfdG9rZW4iLCJyZWFkX3Rva2VuIiwiY2hhcmdlX3Rva2VuIiwiY3JlYXRlX3Byb2dyYW0iLCJyZWFkX3Byb2dyYW0iLCJjcmVhdGVfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIiwicmVhZF9wcm9ncmFtX3BhcnRpY2lwYXRpb24iLCJtb2RpZnlfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIl0sImV4cCI6MTUzNzM4MDczNiwiYXV0aG9yaXRpZXMiOlsiTUNOX0FQSV9UT0tFTl9DSEFSR0VSIiwiTUNOX0FQSV9UT0tFTl9DUkVBVE9SIiwiTUNOX0FQSV9BRE1JTiJdLCJqdGkiOiI4YzI2Njg1MC00NjMzLTQzZDMtYjZjOC1lNzIyY2ExNjQ1YTUiLCJjbGllbnRfaWQiOiI1MjE3NjhhYTc1OGQxMWU4YWE2YjAwNTA1NjlkMTU4NSJ9.HRYXZFATkIcI2_LJ1W_xo67IfBnbN9atyYNzyHqseLxYUxzgwBsAV5rNqCixKemOrDIeQLBN4jrwRsBIHDpEvshwBC8XmTodDJzpGmMaU9s1r20RV68X0_d1yTgSDke_Of7VCrVmJRbSuDl7AgsfTqQ1J7nWyu9vcIaER93ms-vadser_Ot9Z68_HAmCJL3DCLpdIFq3PYtBMKKKqXbvhfhSZQZD3b6-aewAnBo0VzpvK6tREqw1rv9_73oAvYcW2aHAj79ILr8viWMM40LyDKMMYOYkneg3hJUQsUVeh9WzztYUJKzERYNXje9fYIGN-eofoLvX7OZJ3eXmIfkrfQ',\n'Content-Type' => 'application\/json'\n));\n\/\/ Parameters begin here\n$request->setBody('{ "clientAccnum": 900000, "clientSubacc": 0, "customerInfo": { "customerFname": "Tyler", "customerLname": "Thomas", "address1": "Woodland Drive", "address2": "Apt 21", "city": "Tempe", "state": "AZ", "zipcode": "85281", "country": "US", "phoneNumber": "5555555555", "email": "tthomas@xyz.com", "ipAddress": "10.70.60.14", "browserHttpUserAgent": "Mozilla\/5.0 (Windows NT 6.1; Win64; x64; rv:60.0) Gecko\/20100101 Firefox\/60.0", "browserHttpAccept": "text\/html,application\/xhtml+xml,application\/xml;q=0.9,*\/*;q=0.8", "browserHttpAcceptLanguage": "en-US,en;q=0.5", "browserHttpAcceptEncoding": "gzip, deflate, br" }, "paymentInfo": { "creditCardPaymentInfo": { "cardNum": "4473707989493598", "nameOnCard": "Tyler Thomas", "expMonth": "04", "expYear": "2019", "cvv2": "123" } }, "subscriptionId":900000000000000001, "timeToLive": 30, "validNumberOfUse": 3 }');\n\/\/ Parameters end here\ntry {\n$response = $request->send();\necho $response->getBody();\n} catch (HttpException $ex) {\necho $ex;\n}\n?><\/code><\/pre>\n\n\n\nStep 5: API Server Response<\/h3>\n\n\n\n
{ "createdDatetime": "datetime-only", "timeToLive": "integer", "originalPaymentTokenId": "string", "validNumberOfUse": "integer", "clientAccnum": "integer", "clientSubacc": "integer", "programParticipationId": "integer", "avsResponse": "string", "paymentTokenId": "string", "paymentInfoId": "string", "cvv2Response": "string", "subscriptionId": "integer" }<\/code><\/pre>\n\n\n\n1xx Codes<\/h4>\n\n\n\n