-
Notifications
You must be signed in to change notification settings - Fork 11
/
netellerapi-apiary.apib
4449 lines (3550 loc) · 202 KB
/
netellerapi-apiary.apib
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
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
FORMAT: 1A
HOST: https://api.neteller.com/v1
# Integrating the NETELLER REST API
> **!!ATTENTION!!- Mandatory NETELLER API Change Reminder** <br/><br/>
> Paysafe will no longer accept transactions requested through this API as of 15 May 2020. In order to continue transaction processing
> via the NETELLER service you must integrate these new functions via the Paysafe Payments API prior to this date.
> <br/><br/>
> **On 16 November 2020, Paysafe will deactivate the Customer Lookup, Orders, Subscriptions and Plans functions currently available via the NETELLER REST API.**
> <br/><br/>
> Please note, the Customer Verification tool, https://api.neteller.com/v1/customers/verify/{ID}, will remain unaffected. This tool will continue to allow you
> to confirm whether the customer profile in your system matches the account details held within the NETELLER system.
> <br/><br/>
> Please see the <a href="https://developer.paysafe.com/en/additional-documentation/neteller-migration-guide/overview/">NETELLER Migration Guide</a> for more information.
The NETELLER REST API is comprehensive api that allows you to securely manage and facilitate your online payment needs.
The _RESTful API_ ([REpresentational State Transfer](http://en.wikipedia.org/wiki/Representational_state_transfer))
provides predictable, resource based URI's that removes the complexity that often comes with implementing
traditional SOAP or XML driven APIs.
<br/><br/>
This API leverages _OAUTH2_ as a token based authorization framework and works with JSON request and
response object notation.
> The cURL samples included in this documentation are for reference purposes only. Substitute your own
> values as appropriate. You can also refer to the [online cURL documentation](http://curl.haxx.se/docs/manpage.html)
> for additional information on how to use cURL. <br/>
> <br/>
> The following flags are optional and may be useful during testing:<br/>
> <br/>
> `-k : (SSL) This option explicitly allows curl to perform "insecure" SSL connections and transfers.`
> `All SSL connections are attempted to be made secure by using the CA certificate bundle `
> `installed by default. This makes all connections considered "insecure" fail unless -k, `
> `--insecure is used. THIS SHOULD NEVER BE USED IN A PRODUCTION IMPLEMENTATION!`
> `Note that if you only want HTTP headers in the output, -i, --include might be the option you're looking for.`
> <br/>
> <br/>
> `-v : Makes the fetching more verbose/talkative. Mostly useful for debugging. A line starting with '>' means`
> `"header data" sent by curl, '<' means "header data" received by curl that is hidden in normal cases, and a`
> `line starting with '*' means additional info provided by curl.`
# Release Notes
> Please see the section on Versioning to find out how to verify which Minor Version of the API you are using. You
> can choose to upgrade to a newer version at anytime through API Settings of your merchant dashboard.
|API Version|Minor Version |Patch / Description|
|--- |--- |---|
|<b>v1</b> |<b>2015-04-28</b>|**_2021-08-16_**|
| | |Added new parameter: Balances|
| | |Updated ComplexJSON Objects section with accountBalance|
|<b>v1</b> |<b>2015-04-28</b>|**_2020-11-02_**|
| | |- AccountId added to response on customer verification|
| | |**_2018-06-18_**|
| | |- Added new currencies: Chinese Yuan Renminbi \(CNY\)|
| | |- Added Simplified Chinese (zh_CN)|
| | |**_2018-01-27_**|
| | |- Added new currencies: Colombian Peso \(COP\)|
| | |**_2016-01-24_**|
| | |- Added new scope for account\_basic\_profile and updated the accountProfile object to restrict values returned|
| | |- Added new customer verify endpoint|
| | |- Added new payment list endpoint|
| | |- Updated paymentMethod to make NETELLER optional|
| | |**_2015-11-24_**|
| | |- Added transactionType to the the transaction object|
| | |**_2015-10-20_**|
| | |- Added payment method for NETELLERgo! \(paysafecard\)|
| | |- Removed deprecated payment method for NETELLERgo! \(ukash\)|
| | |- Added new currency: Emirati Dirham \(AED\)|
| | |**_2015-09-15_**|
| | |- Added payment methods for NETELLERgo! \(qiwi, yandex, webmoney\)|
| | |- Added F/X support for orders presented in different currencies|
| | |- Added support for one-step payments in NETELLERgo!|
| | |**_2015-08-11_**|
| | |- Added payment method for NETELLERgo! \(boku\)|
| | |**_2015-07-07_**|
| | |- Added ability to lookup all subscriptions for a customer|
| | |- Added new currencies: South African Rand \(ZAR\), Brazilian Real \(BRL\)|
| | |**_2015-06-02_**|
| | |- Added payment method for NETELLERgo! \(bitcoin\)|
| | |- Added pending status to NETELLERgo! and support for on_pending redirect|
| | |**_2015-04-28_**|
| | |- Added status to order resource|
| | |- Added billingDetail resource|
| | |- Updated create order to take an optional array of billingDetail instead of payerProfile|
| | |- Updated lookup payment to return optional billingDetail if payment is made as a guest and not a NETELLER member|
| | |- Added invoiceId to invoice resource|
| | |- Replace customer reference in subscription/order invoice lookup with billingDetail|
| | |- Add HATEOAS link for corresponding customer detail for invoice lookup if they authenticated to NETELLER to pay|
| | |- Create subscription requires a customer id now instead of profile \(The customer id is obtained using the authorization flow\)|
| | |- Added error codes: 20009, 20301|
|<b>v1</b> |<b>2015-11-04</b>|- **_2015-03-24_**|
| | |- Added additional webhooks for orders, payments|
| | |- Added payment methods for NETELLERgo! \(bradesco, bancodobrasil, itau, webpay\)|
| | |- Enhanced OAUTH authorization flow to return customer id for an authorization|
| | |- Added new currencies: Nigerian Naira \(NGN\), Taiwan New Dollar \(TWD\)|
| | |- **_2015-02-10_**|
| | |- Added payment methods for NETELLERgo! \(ideal\)|
| | |- Added multifactor authentication support to OAUTH / NETELLERgo! flows|
| | |- Added payment HATEOAS link to invoice resources|
| | |- Set subscription start times to 00:00:00 and end times to 23:59:59|
| | |- Ensure URLs returned from sandbox properly refer to sandbox host server|
| | |- Removed support for deprecated currencies: Latvian Lats \(LVL\), Lithuanian Litus \(LTL\)|
| | |- **_2014-12-09_**|
| | |- Added support for NETELLERgo!|
| | |- Added payment methods for NETELLERgo! \(sofort, poli, giropay, ukash\)|
| | |- Added order, paymentMethod, redirect resources|
| | |- Modified invoice resource to support order invoices|
| | |- Added order lookup|
| | |- Added lookup invoice for an order|
| | |- Added error codes: 20016|
| | |- **_2014-11-04_**|
| | |- Renamed account resource to customer|
| | |- Updated customer lookup to new resource uris \(/v1/account -> /v1/customer\)|
| | |- Removed linkbackurl from accountProfile resource and moved to root of create customer request|
| | |- Return customer resource instead of accountProfile on payment, subscriptions, invoices resources|
| | |- Renamed subscriptionPlan resource to plan|
| | |- Renamed invoice amountDue to totalAmount|
| | |- Lists no longer contain un-necessary object wrapper, rather returns a list of the appropriate object.|
|<b>v1</b> |<b>2014-04-15</b>|- **_2014-09-30_**|
| | |- Added API minor version support|
| | |- **_2014-09-03_**|
| | |- Added OAUTH2 authorization grant|
| | |- Added account, balance resources|
| | |- Added account lookup functionality|
| | |- Added new scopes: subscription\_payment, account\_enhanced\_profile, account\_contacts, account\_balance|
| | |- Modified create subscription to require scope: subscription_payment|
| | |- **_2014-07-22_**|
| | |- Added Quick Signup functionality|
| | |- **_2014-06-17_**|
| | |- Added ability to list subscription invoices and subscription plans|
| | |- Added subscription invoice lookup|
| | |- Added subscription webhooks|
| | |- Added error codes: 20050|
| | |- Added new languages Greek \(el\_GR\), Korean \(ko\_KR\)|
| | |- Added new subscription status: pending|
| | |- **_2014-05-21_**|
| | |- Added ability to list invoices for a subscription|
| | |- Added support for resource expansion|
| | |- Added new currencies: Malaysian Riggit \(MYR\), Moroccan Dirham \(MAD\), Tunisia Dinar \(TND\) and Swiss Franc \(CHF\)|
| | |- Added error codes: 20102<|
| | |- **_2014-04-15_**|
| | |- Modified authentication to OAUTH2 authentication using client_credentials|
| | |- Added subscription billing support|
| | |- Added error codes: 20100, 20101|
## 2014-11-04 Upgrade Notes
The following page outlines items to review when upgrading your REST API from v1 \(2014-04-15\) to v1 \(2014-11-04\).
> You can trial your upgraded integration with your TEST sandbox account prior to upgrading in production. Contact NETELLER Merchant Support if you require assistance with your sandbox account.
Upgrade Procedure
1. Modify any calls to /v1/accounts to the new /v1/customers resource
2. If you are looking up profile details using the the former call /v1/accounts/{accountId} this should now change to this format /v1/customers/?accountId={accountId}.
3. To query for a profile using email, the same convention is used but the resource uri should change as follows: /v1/customers/?email={email}.
4. When creating customers (formerly accounts), you now post an accountProfile to the new endpoint /v1/customers and receive a customer object in response. If linkbackurl was previously supplied as part of the accountProfile, this has been moved to the root of that request and is no longer part of the accountProfile.
5. Ensure any embedded references to accountProfile information are updated to refer to customer details
## 2015-04-28 Upgrade Notes
The following page outlines items to review when upgrading your REST API from v1 \(2014-11-04\) to v1 \(2015-04-28\).
If you are upgrading directly from v1 \(2014-04-15\), then you should first consider the changes outlined in the the 2014-11-04 Upgrade Notes.
> You can trial your upgraded integration with your TEST sandbox account prior to upgrading in production. Contact NETELLER Merchant Support if you require assistance with your sandbox account.
Upgrade Procedure
1. Modify create order calls to supply an array of billingDetail instead of payerProfile. Only one billingDetail is permitted at this time.
2. Modify invoice lookups to use billingDetail instead of cusomer resource.
3. If you are using our subscription services, the create subscription now requires the customerId instead of the NETELLER account id OR email. When you ask your customer for permission to create a subscription through the authorization flow, you will be returned the customerId that provided the authorization. If you have already received authorization from your customer and do not want to have to have them re-authorize, you can use the customer lookup call to identify the customerId for their account.
4. Payment lookups will now only return a customer object if the payment is related to an account holder. For NETELLERgo! checkouts that are performed by guests, a billingDetail block will be returned.
# Technical introduction
This section provides a technical introduction to the NETELLER REST API.
## API Endpoints
The NETELLER REST API is available in the sandbox environment for integration testing purposes. To switch between the sandbox and the live production system you only need to change the endpoint URI and the credentials.
The following endpoints form the basis of a resource URI:
* **Sandbox (Testing) endpoint -**
`https://test.api.neteller.com`
* **Production endpoint -**
`https://api.neteller.com`
_As the sandbox environment is completely isolated, any changes you perform on your sandbox accounts configuration (such as secure IP registration, APP registration) may have to be repeated in your production account._
## Versioning
The first time you make an API request, NETELLER will automatically record the the current API version and associate it with your merchant account.
<br/><br/>
The API version will influence the request/response object structure as well as the functionality that is available through the API. A new version of the API will only be introduced if we roll out a backwards incompatible change that may impact your existing integrations. As your API version can be maintained through the merchant portal, you can manage when to upgrade to the latest version, helping ensure your integration is not disrupted as new functionality becomes available.
> You can update your API version from the merchant dashboard. This is a manual process. NETELLER recommends you check back
> periodically to see if new versions are available as there may be key enhancements that have been released that
> would improve your integration.
> 
_Outdated minor versions of the API will be supported for 12 months, after which point they may be deprecated and you will be required to upgrade to a newer version._
### Major Version
The major version \(ie: /v1/ \) represents a major technology shift between versions of the API. Changes in the major version are reserved for large scale changes to the API that fundamentally change integration requirements from the previous version. Modified business domain models, re-design of functional flows or change in API resource patterns are all considered major changes. Changes to major version are rare and typically require an extended deprecation cycle \(~2 years\) from prior versions to allow all consumers of the API to adapt.
### Minor Version
The minor version is a date stamped version of the API indicating when a backwards incompatible change was released in production. Only changes that are deemed backwards incompatible will trigger a new minor version. Other changes that are considered backwards compatible are integrated in the last version and rolled out as patches as soon as they become available. The minor version is NOT specified as part of the URL request, it is defined as part of your merchant account and can be controlled through your merchant account portal.
<br/><br/>
_When working with the REST API, you should treat any identity fields returned by NETELLER as strings so that in the event we change the structure of the ID, it will not break your integration._
<br/><br/>
**What is considered a backwards compatible change?**
* Adding API resources or adding new properties to existing API resources
* Modification to the order of parameters or JSON object elements
* Adding optional request parameters to API methods
* Adding webhook event types
**What is considered a backwards incompatible change?**
* Removal of a API resource
* Removal of an API Resources object attribute
* Changes to required parameter / JSON object elements
* Removal of previously supported API call
## Pagination
REST calls that return multiple resources will wrap the response as a JSON array named 'list'. By default, 10 items will be returned at a time and you can navigate to the next page of data using the returned HATEOAS links.
Any list results will also include a meta data section that will identify the number of records included in the collection,
the number of records per page (limit) and current page number.
<br/><br/>
For example, if a request to look up subscriptions identifies that there are 134 subscriptions and you have set your limit to 15, the first 15 items will be returned with navigation links to the next 15 items in the list \(items 16-30\). If you navigate to the next page using the provided HATEOAS link, you will now retrieve items 16-30 with a new navigation link provided to return to the previous page, as well as a link to continue to the next page of items._
> _You can change the default list page size by defining a **limit** parameter value._
|Parameter Name |Description|
|--- |---|
|limit |The number of records to be returned per page. Default = 10, Max = 100|
|offset |Identifies your location within the list and allows you to fetch the next set of resources|
Sample Response with List Data
```
{
"meta": {
"numberOfRecords": 77,
"limit": 10,
"page": 2
},
"list": [
{
"planId": "MONTHLYGREENPLAN",
"planName": "Sample Premier Monthly Membership",
"interval": 3,
"intervalType": "monthly",
"intervalCount": 4,
"amount": 2995,
"currency": "EUR",
"status": "active"
},
{
...
},
{
...
},
],
"links": [
{
"url": "https://api.neteller.com/v1/plans?sessionid=234243242&limit=10&offset=10",
"rel": "self",
"method": "GET"
},
{
"url": "https://api.neteller.com/v1/plans?sessionid=234243242&limit=10&offset=0",
"rel": "prev_offset",
"method": "GET"
},
{
"url": "https://api.neteller.com/v1/plans?sessionid=234243242&limit=10&offset=20",
"rel": "next_offset",
"method": "GET"
}
]
}
```
## Resource Expansion
Resource expansion can be compared to eager loading in the database realm. It offers a way to load a specific resource as well as other resources related to it. You are encouraged to use resource expansion when you know you are going to need the extra information. This will reduce the amount of API calls as well as the amount of traffic to and from your server. You should avoid resource expansion when you want to reduce the amount of information returned or if you are unsure if you will need the additional resource object.
<br/><br/>
By adding an **expand** query parameter to the query you are effectively telling the server to include the details for the reference object in-line, in a expand single response. Anytime you encounter an object whose only child attribute is a link, you can consider that object expandable. Passing that object name as part of your expand parameter list will automatically substitute the link with the relevant details.
<br/><br/>
For resources that have multiple expandable children, you can specify which resources to expand in a comma separated list. <br />
Eg. <b>?expand=resource1,resource2</b>
<br/>
> _Resource expansion does not apply to API requests that return a list._
<br/>
Below is a sample subscription lookup. By default the plan and customer resources are not expanded and instead includes a
reference link that would provide the relevant details. If you would rather have the full subscription plan object returned,
then add the **'expand=plan'** parameter to your request and you will see the second example result.
<br/>
*Result without resource expansion*
```
{
"subscriptionId": "234234224",
"plan": {
"link": {
"url": "https://api.neteller.com/v1/plan/MONTHLYGREENPLAN",
"rel": "plan",
"method": "GET"
}
},
"customer": {
"link": {
"url": "https://api.neteller.com/v1/customers/CUST_0d676b4b-0eb8-4d78-af25-e41ab431e325",
"rel": "customer",
"method": "GET"
}
},
"status": "active",
"startDate": "2014-06-01T00:00:00Z",
"endDate": "2014-12-31T00:00:00Z",
"currentPeriodStart": "2014-07-01T00:00:00Z",
"currentPeriodEnd": "2014-07-31T00:00:00Z",
"cancelAtPeriodEnd": false,
"cancelDate": null,
"lastCompletedPaymentDate": "2014-06-31T00:00:00Z",
"links": [
{
"url": "https: //api.neteller.com/v1/subscriptions/234234224",
"rel": "self",
"method": "GET"
}
]
}
```
*Result with the plan resource expanded*
```
{
"subscriptionId": "234234224",
"plan": {
"planId": "MONTHLYGREENPLAN",
"planName": "Sample Premier Monthly Plan",
"interval": 3,
"intervalType": "monthly",
"intervalCount": 4,
"amount": 2495,
"currency": "EUR",
"status": "active"
},
"customer": {
"link": {
"url": "https://api.neteller.com/v1/customers/CUST_0d676b4b-0eb8-4d78-af25-e41ab431e325",
"rel": "customer",
"method": "GET"
}
},
"status": "active",
"startDate": "2014-06-01T00:00:00Z",
"endDate": "2014-12-31T00:00:00Z",
"currentPeriodStart": "2014-07-01T00:00:00Z",
"currentPeriodEnd": "2014-07-31T00:00:00Z",
"cancelAtPeriodEnd": false,
"cancelDate": null,
"lastCompletedPaymentDate": "2014-06-31T00:00:00Z",
"links": [
{
"url": "https: //api.neteller.com/v1/subscriptions/234234224",
"rel": "self",
"method": "GET"
}
]
}
```
## OAUTH Authentication
NETELLER REST APIs are based on the OAUTH2 standard as defined by [RFC6749](http://tools.ietf.org/html/rfc6749) and require that you supply a valid OAUTH2 access token with each API request.
The REST APIs utilize a 'bearer' token. For more information on bearer tokens see: [draft-ietf-oauth-v2-bearer-23.txt](http://tools.ietf.org/id/draft-ietf-oauth-v2-bearer-23.txt)
### Obtain an access token
To access the NETELLER REST APIs, you will require an access token that can be obtained from the NETELLER OAUTH2
token endpoint. Obtain an access\_token by making a request to the NETELLER Token endpoint with the appropriate
grant_type identified.
> To obtain access tokens you must first register your client \(application\) you wish to integrate with. APP
> registration can be completed from your merchant account portal and will provide you with your APP specific
> client_id and client_secret. By default, the access token is a short lived one-time use token that expires
> in 5 minutes. If your integration requires frequent callbacks and you would like to be able to re-use the
> access token, or require an extended token expiry time, please contact NETELLER Merchant Support to have your
> APP settings adjusted accordingly.
The NETELLER Platform supports the following OAuth 2.0 flows
**client_credentials grant**
Allows you to request an access token using only the client credentials provided to you. This grant is used to access API functions that are under your control, and that do not require member authorization.
**authorization_code grant**
If your API request requires member permission (required scope permissions are identified in the section detailing each API operation), you will be required to use the authorization_code grant flow and will have an additional step of obtaining member authorization before you can obtain an access token. This flow requires you to redirect your users to the authorization server where they will authenticate as a NETELLER member and approve the requested permissions. The supplied auth_code can then be exchanged for an access_token allowing you access API functions on the members behalf.
The client must be capable of interacting with the resource owner's user agent \(typically a web browser\) and capable of receiving incoming requests \(via redirection\) from the authorization server.
> These flows are intended for clients capable of maintaining their client credentials in a confidential manner, such as a client implemented on a secure server \(https\)
**OAUTH2 Workflow Diagram**
#### Obtain an access token using the client_credentials grant type
You can request an access token using only your client credentials \(client\_id:client\_secret\).
> Your client credentials consist of a unique client_id and client_secret that can be found under the registered APPs section of your NETELLER Merchant Account.
> The Authorization header should be constructed to pass a base64 encoded version of these values \(client_id:client_secret\). If you are testing using cURL or a browser client, you can specify the HTTP Basic credentials by using the client_id as your username and client_secret as your password.
> <br/><br/>
> The client_secret for your application should not be shared with anyone or embedded in any code that you will distribute. This exclusion also extends to an app binary that could be de-compiled. This API call should only be made using server-side code over TLS.
**Request Parameters**
|Parameter Name |Required? |Description|
|--- |--- |---|
|grant\_type |required |set to `client_credentials`|
**Sample Request #1 \(using HTTP Basic Authorization\)**
> The authorization value is equal to Basic: Base64Encoded\(client\_id:client\_secret\)
```
curl -X POST \
-H "Authorization:Basic QUFBQlJiUkh3V2tzbG8tdTowLmtnOG1wSnhOeER5ZUx2SVNVZ04wbHFsWWVWQS1UeFZSWlVFWThIdWljOEEuUzRuRnpPWS0wLTF3bW1qd3lGV2l0aUZwRGxz" \
-H "Content-Type:application/json" \
-H "Cache-Control:no-cache" \
https://api.neteller.com/v1/oauth2/token?grant_type=client_credentials
```
**Sample Request #2 \(cURL specific sample, using client\_id and client\_secret as username/password\)**
```
curl -X POST \
-u "AAABRbRHwWkslo-u:0.kg8mpJxNxDyeLvISUgN0lqlYeVA-TxVRZUEY8Huic8A.S4nFzOY-0-1wmmjwyFWitiFpDls" \
-H "Content-Type:application/json" \
-H "Cache-Control:no-cache" \
https://api.neteller.com/v1/oauth2/token?grant_type=client_credentials
```
**Response Structure**
|Field Name |Field Type |Constraints |Description|
|--- |--- |--- |---|
|accessToken |string |length <= 200 |The access token to be used in calls to the protect NETELLER REST APIs.|
|tokenType |string |length <= 50 |Identifies the type of token to the client. Possible values: `Bearer`|
|expiresIn |number | |The lifetime in seconds of the access token.|
> A refresh token WILL NOT be included for this grant type. It is only applicable for type: authorization_grant
**Sample Response**
```
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"accessToken":"0.AQAAAUW-9Tu4AAAAAAAEk-BNppPGFNwoWODBcOzrnHwA.skB0dDtyMrW4xCZJw__FGNtL-08",
"tokenType":"Bearer",
"expiresIn":300
}
```
If the request failed client authentication or is invalid, the authorization server returns an [error response](#OAUTH Errors).
```
{
"error": "unsupported_grant_type"
}
```
#### Obtain an access token using the auth_code grant type
> *Is member authorization required?*
> If the API resource does not require member authorization \(identified by a scope of *'default'*\), you can Obtain an access token using the client_credentials grant type instead.
The authorization grant flow has two parts and utilizes two authorization server endpoints.
*1\) Authorization Endpoint* - used to obtain authorization \(auth_code\) from the resource owner via user-agent redirection.
Your application redirects the member to NETELLER where they are asked to grant the requested permissions. if the member approves,
NETELLER will post back to your redirect uri with a unique authorization code that represents this members acknowledgement of your
request.
*2\) Token Endpoint* - used to trade in the auth\_code, or previously issued refresh_token for an new access token
The authorization code can then be exchanged for an access_token to use with your REST API calls. This process can be repeated until
authorization is revoked by the member or until different permissions are required.
**The flow consists of the following steps:**
1. The client app requests authorization by redirecting the user to the authorization endpoint.
2. The resource owner (member) must verify their identity via a hosted authentication page.
3. The resource owner (member) is prompted to authorize the application. The requested scopes are displayed and the member must Allow or Deny the authorization.
4. If the member authorized the requested scope, an auth_code is returned to your redirect uri. This code will have a limited lifetime for you to complete the callback to redeem the access token.
5. Now you need to authorize your app. Call the token endpoint with a grant type of authorization_code and provide the auth code from step 4. If successful, an access token is returned that can be used to make API requests on the users behalf.
> When invoking this flow, you must pass in the redirect\_uri that the user's browser will be redirected back to once app authorization is completed. The redirect_uri must be the same URI you specify when registering your web application OR must be the same one that was passed in the original authorization call.
**Obtain an authorization code**
```
GET https://api.neteller.com/v1/oauth2/authorize?client_id=YOUR_APPLICATION_ID&redirect_uri=YOUR_URI&scope=YOUR_REQUESTED_SCOPE&response_type=code
```
**Authorization Request Parameters**
|Parameter Name |Required? |Description|
|--- |--- |---|
|client_id |required |Unique identifier generated when you registered your application.|
|redirect\_uri |optional |The uri that the user's browser will be redirected back to once app authorization is completed. If supplied during this authorization request, the same uri must be supplied in the call to the token endpoint. When not supplied, the default registered redirect uri will be used. The redirect_uri must secured over TLS \(https://\)|
|scope |required |The supplied scope parameter will indicate the level of access you require for your app. The scope parameter MUST be supplied. If your application requires multiple scopes then you should supply a comma separated list. Eg. scope=perm1,perm2|
|state |optional ||
|response_type | |Identifies the type of response for this request. Valid values: code - for server side flows **Only code is permitted at this time |
|lang | |OPTIONAL: preferred language to render the authorization flow in. see [Languages](#Languages) for complete list|
The following request sample shows how to ask for authorization to obtain a members balance to show on your cashier page.
```
GET https://api.neteller.com/v1/oauth2/authorize?client_id=AAABRbRHwWkslo-a&redirect_uri=https://www.mysite.com/cashier&scope=account_available_balance&response_type=code
```
The following flows will be presented:
Member Authentication - Member will need to verify their identify using their standard credentials.
Member will be prompted to authorize the requested permissions.
**Authorization Response Structure**
*Authorization Success*
If the member authorizes your request NETELLER will redirect \(via HTTP 302\) the user's browser by adding the following parameters to the query component of the redirection URI using the
"application/x-www-form-urlencoded" format.
|Parameter Name |Description|
|--- |---|
|code |A short lived authorization code that can be exchanged for an access token. This value is short lived \(10 minutes\) and must be exchanged for a valid access token before it expires.|
|state |Will be provided if the state parameter was present in the authorization request.|
|customer_id |The associated unique identifier for this NETELLER account holder. This identifier can be used to lookup additional information about the customer.|
*Sample Response*
```
https://https//www.mysite.com/cashier?auth_code=0.AAAAAUmlhiRUAAAAAAAEk-DKmil1fF5vleYLDaiRhPDi.si-fsMDooIjhdGrShvafUALhQP8&state=abc&customer_id=CUS_F493C864-69D1-4939-B914-CC4C52A57DEF
```
**Exchange your authorization code for an access token**
Once you have received member authorization, you can exchange your authorization_code for an access token.
```
POST https://api.neteller.com/v1/oauth2/token?grant_type=authorization_code&code=YOUR_AUTHORIZATION_CODE&redirect_uri=YOUR_REDIRECT_URI
```
*Token Request Parameters*
|Field Name |Field Type |Field Size |Required? |Description|
|--- |--- |--- |--- |---|
|grant\_type |string |100 |required |set to 'authorization_code'|
|code |string |20 |required |set to the auth_code previously received from the authorization server.|
|redirect\_uri |string |500 |optional |The TLS enabled redirection uri that will be returned to. This value must match the uri used to obtain authorization, If not supplied during the authorization flow then the redirect_uri will be the registered redirect uri for your application \(as set in the merchant.com portal under the APPS section\) and should not be passed.|
*Sample Request #1 \(using client_id and client_secret as username/password\)*
```
curl -X POST \
-u "AAABRbRHwWkslo-u:0.kg8mpJxNxDyeLvISUgN0lqlYeVA-TxVRZUEY8Huic8A.S4nFzOY-0-1wmmjwyFWitiFpDls" \
-H "Content-Type:application/json" \
-H "Cache-Control:no-cache" \
"https://api.neteller.com/v1/oauth2/token?grant_type=authorization_code&code=0.AAAAAUfvVDS3AAAAAAAEk-B5Ei4gPXAQA4B8EDH4jpdC._Cm7iYsUq1SQgJNiZg11yQwfpEg&redirect_uri=https://www.mysite.com"
```
*Sample Request \(using HTTP Basic Authorization\)*
The authorization value is equal to Basic: Base64Encoded\(client\_id:client_secret\)
```
curl -X POST \
-H "Authorization:Basic QUFBQlJiUkh3V2tzbG8tdTowLmtnOG1wSnhOeER5ZUx2SVNVZ04wbHFsWWVWQS1UeFZSWlVFWThIdWljOEEuUzRuRnpPWS0wLTF3bW1qd3lGV2l0aUZwRGxz" \
-H "Content-Type:application/json" \
-H "Cache-Control:no-cache" \
"https://api.neteller.com/v1/oauth2/token?grant_type=authorization_code&code=0.AAAAAUfvVDS3AAAAAAAEk-B5Ei4gPXAQA4B8EDH4jpdC._Cm7iYsUq1SQgJNiZg11yQwfpEg&redirect_uri=https://www.mysite.com"
```
If your app is successfully authenticated, and the authorization code is valid, the authorization server will return the following:
**Token Request Success**
*Response Structure*
A [token](# Complex JSON Objects) object will be returned.
|Field Name |Field Type |Field Size |Description|
|--- |--- |--- |---|
|accessToken |string |100 |The access token to be used in calls to the protect NETELLER REST APIs.|
|tokenType |string |20 |Identifies the type of token to the client. For now only 'Bearer' is supported.|
|expiresIn |number |6 |The lifetime in seconds of the access token. Default is 300 seconds \(5 minutes\).|
|refreshToken |string |100 |The refresh token which can be used to obtain new access tokens using the same authorization grant that was previously associated to it. This value is a secret. You should treat it like the user's password and take appropriate measures to protect it.|
|scope |string |250 |The scope associated with the access token.|
*Sample Response*
```
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"accessToken": "0.AQAAAUgUGIk5AAAAAAAEk-CgJxQeNBiq7ES8yQaLITPU.JGrVsVsiy3ASoQsYED9VkJv25eY",
"tokenType": "Bearer",
"expiresIn": 300,
"refreshToken": "0.AgAAAUgUGIkyAAAAB1jwsODI5PCkVNOZul5AJ01mYtdh.ezGCYhN5YD22-BCOPX6U-muc72o",
"scope": "subscription_payment"
}
```
#### Obtain an access token using your refresh token
If the previously issued access token has expired \(obtained from the authorization grant authentication flow\)
and you receive a HTTP 401 - Unauthorized error, you can utilize the refresh token that was issued to you with
the initial authorization response to obtain a new one.
*Request Parameter*
|Parameter Name |Required? |Description|
|--- |--- |---|
|grant\_type |required |set to 'refresh_token'|
|refresh\_token |required |The refresh token previously issued to the client|
*Sample Request*
```
curl -X POST \
-H "Authorization:Basic QUFBQlJiUkh3V2tzbG8tdTowLmtnOG1wSnhOeER5ZUx2SVNVZ04wbHFsWWVWQS1UeFZSWlVFWThIdWljOEEuUzRuRnpPWS0wLTF3bW1qd3lGV2l0aUZwRGxz" \
-H "Content-Type:application/json" \
-H "Cache-Control:no-cache" \
"https://api.neteller.com/v1/oauth2/token?grant_type=refresh_token&refresh_token=0.AgAAAUnPnWEeAAAAB1jwsOAq6iK0G2op1zi_sQC3KE22.oD4wHNZjuF5tWOZh2ozEpi2E7BE"
```
*Response Structure*
|Field Name |Field Type |Field Size |Description|
|--- |--- |--- |---|
|accessToken |string |length <= 200 |The access token to be used in calls to the NETELLER REST APIs.|
|expiresIn |number | |The lifetime in seconds of the access token.|
|tokenType |string |20 |Identifies the type of token to the client. "Bearer"|
|scope |string | |The comma delimited list of scopes that have been authorized for this token.|
*Sample Response*
```
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"accessToken": "0.AQAAAUfvtyJyAAAAAAA27oALPWxe111yJMNH3HEa6l_o.EddShan6OS7sQX28UhYz5cz_LHE",
"expiresIn": 300,
"tokenType": "Bearer",
"scope": "subscription_payment, account_available_balance"
}
```
## OAUTH Errors
####Authorization Request Errors
If the member does not authorize your request, or the request fails for reasons other then a missing or invalid redirection URI NETELLER will redirect \(via HTTP 400 - Bad Request\) the user's browser by adding the following parameters to the query component of the redirection URL using the "application/x-www-form-urlencoded" format.
> There are some error situations in which you will not receive the error back on your redirect_uri. For example, if you attempt to supply an insecure http:// redirect. In this case the customer would see an invalid request error. For this reason it is important to validate your integration!
|Parameter Name |Description|
|--- |---|
|error |The error that occurred|
|error_description |Reason for the error.|
|state |Will be provided if the **state** parameter was present in the authorization request|
Possible Errors:
|Error |Error Reason|
|--- |---|
|**invalid_request** |The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.|
|**unauthorized_client** |The client is not authorized to request an authorization code using this method.|
|**access_denied** |The resource owner or authorization server denied your request.|
|**unsupported_response_type** |The authorization server does not support obtaining an authorization code using this method.|
|**invalid_scope** |The requested scope is invalid, unknown, or malformed.|
|**server_error** |The authorization server encountered an unexpected condition that prevented it from fulfilling the request.\(This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect.\)|
|**temporarily_unavailable** |The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. \(This error code is needed because a 503. Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect.\)|
Sample Response
https://YOUR_URL/?error=access_denied&error_description=The+resource+owner+or+authorization+server+denied+your+request
#### Token Request Errors
The authorization server responds with an HTTP 400 \(Bad Request\) status code \(unless specified otherwise\) and includes the following parameters with a JSON response:
|Parameter Name |Description|
|--- |---|
|error |The error that occurred|
|error_description |Reason for the error.|
|state |Will be provided if the **state** parameter was present in the authorization request|
Possible Errors:
|Error |Error Reason|
|--- |---|
|**invalid_request** |The request is missing a required parameter, includes an unsupported parameter value \(other than grant type\), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.|
|**invalid_client** |Client authentication failed \(e.g., unknown client, no client authentication included, or unsupported authentication method\). The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the "Authorization" request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the "WWW-Authenticate" response header field matching the authentication scheme used by the client. **This error might also indicate that you are attempting access from an unauthorized IP address.|
|**invalid_grant** |The provided authorization grant \(e.g., authorization code, resource owner credentials\) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.|
|**unauthorized_client** |The authenticated client is not authorized to use this authorization grant type.|
|**server_error** |The authorization server encountered an unexpected condition that prevented it from fulfilling the request.\(This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect.\)|
|**unsupported_grant_type** |The authorization grant type is not supported by the authorization server.|
|**invalid_scope** |The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.|
## OAUTH Scopes
Some resources available through the NETELLER REST API require that your APP be granted appropriate authorization by the member. This authorization of permissions, also referred to as authorized scope, is managed by directing the NETELLER member to a page where they can choose to approve or deny the requested access.
The following list identifies the authorized scopes that are available in the NETELLER API. These permissions, or scopes, are handled on a per member / per access token basis. To retrieve a resources protected fields, you must first obtain an access token using the authorization grant flow or previously issued refresh token. You can continue to obtain new access tokens for the already authorized scopes until the authorization expires or is revoked by the member.
For API requests that permit default scope, you may not require member authorization if the fields you are concerned with are offered as part of the default response. In this instance you should use your client credentials to obtain the required access token as there is no required member authorization.
> The permissions associated with an access token are set in the /v1/oauth2/authorize call.
Some API methods will limit their response data dependent upon which authorized scopes have been granted. See the JSON Objects reference for details around which fields are returned by default and which ones require member authorization.
|Permission |Authorized Scope |Description|
|--- |--- |---|
|Subscription Payment |subscription_payment |Permits access to setup a subscription and automatically receive recurring payments from a NETELLER account holder<br/>**Member Prompt: Allow access to setup a subscription and receive recurring payments from your NETELLER account.**|
|Basic Profile |account\_basic\_profile |Permits access to your name, date of birth, country<br/>**Member Prompt: Allow access to view your name, date of birth and country.**|
|Enhanced Profile |account\_enhanced\_profile |Permits access to account address, city, post code, subdivision, account preferences and gender<br/>**Member Prompt: Allow access to view your address, account preferences and gender.**|
|Available Balance |account\_available\_balance |Permits access to view the members currently available balance<br/>**Member Prompt: Allow access to view your currently available balance.**|
|Contact Information |account\_contacts |Permits access to the member contact phone numbers.<br/>**Member Prompt: Allow access to view your contact phone numbers.**|
<a name='webhooks'></a>
## Webhooks
A webhook allows you to define an HTTP callback that will be POST to when an event occurs that you would like to be notified of. You can define the notification URL and select which events you wish to be notified of from your merchant account portal.
> Webhooks will be sent whenever the state of the resource changes. Certain activity may lead to the same event being sent more than once.
**Responding to a webhook**
To acknowledge that you received the webhook without any problem, your server should return a 200 HTTP status code. Any other information you return in the request headers or request body will be ignored. Any response code outside the 200 range, including 3xx codes, will indicate to NETELLER that you did not receive the webhook.
> If your system did not respond with a valid HTTP 200 status, NETELLER will continue to retry the request with an escalating time delay for up to 48 hours
**Secure webhooks \(recommended\)**
NETELLER recommends that you use one of the following forms of authentication on your webhook URLs
**HTTP Basic Authentication - Use basic authentication syntax in your webhook URL:**
Format : https://{username}:{password}@{webhook_url}
Example : https://exampleuser:NT1p2dsl@example.com/netellerwebhook
**Secret Key - Provide a secret key that is passed back as part of the webhook event notification body.**
Format : https://{webhook_url}
Example : https://example.com/netellerwebhook
> The secret key should not be shared with anyone.
**Sample webhook response**
```
{
"mode": "live",
"id": "ebecd052-757f-4991-9f19-469d21e6c065",
"eventDate": "2014-01-01T00:00:00Z",
"eventType": "subscription_payment_succeeded",
"attemptNumber": 1,
"key": "23haJ20opHJ2ks38aGEnw",
"links": [
{
"url": "https://api.neteller.com/v1/subscriptions/234234224/invoices/99102",
"rel": "invoice",
"method": "GET"
}
]
}
```
> When sending a Test Webhook request from the merchant portal, the links section will be excluded from the response as their is no valid resource reference to send.
**Subscription resource event**
|Event Types |Event that triggers the webhook|
|--- |---|
|subscription\_activated |Subscription was activated. Also triggered when a subscription has moved from a 'pending' to 'active' state.|
|subscription\_cancelled |Subscription was cancelled.|
|subscription\_cancelled\_at\_period\_end |Subscription is set to be cancelled at the end of the current billing period.|
|subscription\_created |Subscription was successfully created.|
|subscription\_ended |Subscription has lapsed and is now ended.|
|subscription\_failed |Subscription failed to be created. Most likely the account had insufficient funds for initial payment.|
|subscription\_pending |Subscription is created but pending a future activation.|
**Order resource events**
|Event Types |Event that triggers the webhook|
|--- |---|
|order\_cancelled\_or\_expired |Order payment failed, the member did not complete their order in time.|
**Invoice resource events**
|Event Types |Event that triggers the webhook|
|--- |---|
|order\_payment\_declined |Order payment was declined.|
|order\_payment\_succeeded |Order payment was successful.|
|subscription\_payment\_declined |Subscription payment for period was not successful.<bt/>Attempts to collect payment for the subscription for the billing period have failed and no more retries will be attempted.|
|subscription\_payment\_pending\_retry |Subscription payment was not collected as the member has insufficient funds available, <Br/>NETELLER will continue to try to collect payment for this period.|
|subscription\_payment\_succeeded |Subscription payment for period was successful.|
**Payment resource events**
|Event Types |Event that triggers the webhook|
|--- |---|
|payment\_cancelled |Payment was cancelled.|
|payment\_declined |Payment was declined.|
|payment\_pending |Payment is pending.|
|payment\_succeeded |Payment is successful.|
## Merchant Currencies
<a name="currencies"></a>
|Currency Code|Description |Decimal Places|
|--- |--- |---|
|AED |Emirati Dirham |2|
|AUD |Australian Dollar |2|
|BRL |Brazilian Real |2|
|GBP |British Pound |2|
|BGN |Bulgarian Lev |2|
|CAD |Canadian Dollar |2|
|COP |Colombian Peso |2|
|CNY |Chinese Yuan Renminbi |2|
|DKK |Danish Krone |2|
|EUR |Euro |2|
|HUF |Hungarian Forint |0|
|INR |Indian Rupee |2|
|JPY |Japanese Yen |0|
|MYR |Malaysian Ringgit |2|
|MAD |Moroccan Dirham |2|
|MXN |Mexican Peso |2|
|NGN |Nigerian Naira |2|
|NOK |Norwegian Kroner |2|
|PLN |Polish Zloty |2|
|RON |Romanian New Leu |2|
|RUB |Russian Ruble |2|
|SGD |Singapore Dollar |2|
|SEK |Swedish Krona |2|
|CHF |Swiss Franc |2|
|TWD |Taiwan New Dollar |2|
|TND |Tunisia Dinar |3|
|USD |United States Dollar |2|
|ZAR |South African Rand |2|
Note: When specifying amounts in your API calls be aware of the number of decimal places (minor units) that
each currency supports. You must change the formatting of the amount based on the minor units for the
specific currency. For example, Japanese Yen does not have minor units so the amount should be specified as
such. ie: 50 JPY would pass 50 in the amount, 50.00 USD would be an amount of 5000, and 50.000 TND would be 50000.
## Languages
<a name="languages"></a>
|Language Code|Description|
|--- |---|
|da_DK |Danish|
|de_DE |German|
|el_GR |Greek|
|en_US |English|
|es_ES |Spanish|
|fr_FR |French|
|it_IT |Italian|
|ja_JP |Japanese|
|ko_KR |Korean|
|no_NO |Norwegian|
|pl_PL |Polish|
|pt_PT |Portuguese|
|ru_RU |Russian|
|sv_SE |Swedish|
|tr_TR |Turkish|
|zh_CN |Simplified Chinese|
# HTTP Responses
HTTP response codes are used to indicate the status of a request.To ease integration and support for developers
integrating to our APIs, the error messages that are returned should be verbose enough to correct the problem.
The error structure contains a 4–5 digit code as well as a human readable message. Additionally, the application
error code will be returned in the header so it can be easily used by an application without parsing the body.
**HTTP Status Code Summary**
|HTTP Response Code Category|Description|
|---|---|
|1xx: Informational|Communicates transfer protocol–level information|
|2xx: Success|Indicates that the client’s request was accepted|
|3xx: Redirection|Indicates that the client must take some additional action in order to complete the request|
|4xx: Client Error|Indicates that the client has made an error with the request|
|5xx: Server Error|Indicates that an error occurred on the server side|
**Common HTTP Response Status Codes**
|HTTP Status Code|Description|
|---|---|
|200 OK|Everything worked as expected|
|201 CREATED|The request was successful. NETBANX created a new resource and the response body contains the representation|
|202 ACCEPTED|This indicates that the client’s request will be handled asynchronously. It tells the client that the request appears valid, but it still may have problems once it is processed|
|204 NO CONTENT|This is usually returned in response to a PUT, POST, or DELETE request, when the REST API declines to send back any status message or representation in the body of the response message|
|304 NOT MODIFIED|The client's cached version of the representation is still up to date|
|400 BAD REQUEST|This often indicates that a required parameter is missing or that a parameter is invalid. This is a generic client-side error status, used when no other 4xx error code is appropriate|
|401 UNAUTHORIZED|This indicates that the client tried to operate on a protected resource without providing the proper authorization. They may have provided the wrong credentials or none at all|
|402 PAYMENT REQUIRED|The parameters were valid but the request failed|
|404 NOT FOUND|The requested resource does not exist|
|405 METHOD NOT ALLOWED|The client tried to POST or PUT to a resource that would not accept it|
|415 UNSUPPORTED MEDIA TYPE|The request is in a format not supported by the requested resource for the requested method|
|429 TOO MANY REQUESTS|The application is sending too many simultaneous requests|
|500 INTERNAL SERVER ERROR|An error occurred with an internal server|
|502 EXTERNAL SERVER ERROR|We received an invalid response from the upstream gateway in attempting to fulfill the request|
**Error Attributes**
|Element|Type|Description|
|---|---|---|
|Element|Type|Description|
|code|String|This is the error code|
|message|String|This is a description of the error|
|details|Array|This is a detailed description|
|fieldErrors|Array|This is a list of fields that have problems|
**Error message example with details**
```
{
"error": {
"code": "5023",
"message": "Bad request",
"details": [
"Illegal unquoted character ((CTRL-CHAR, code 10)): has to be escaped using backslash to be included in string value at [line: 2, column: 61]"
]
}
}
```
**Error message example with field errors**
```
{
"error":{
"code":5068,
"message":"Field Error(s)",
"fieldErrors":[
{
"field":"recipientEmail",
"error":"john@hi@you.c.c.c.c is not a valid e-mail address."
},
{