README

本项目包含用于iGivefirst捐赠API的PHP SDK。它以Composer包的形式分发，便于访问。

示例用法

<?php

require 'vendor/autoload.php';

$nonprofit_campaign = '1e9a8366-1060-4b45-9874-95039ec217c6';
$publisher_campaign = 'b93babc1-9557-4271-a065-43b29f04c2fb';

$igf = new iGivefirst(API_KEY, API_SECRET);

// Create a new Donor
$donor = new DonorInfo();
$donor->setUser(time() . '@igivefirst.mobi');
$donor->bind(array('firstName'=>'John', 'lastName'=>'Doe', 'billingAddress1' => '123 Candy Lane', 'city' => 'Imaginary', 'state' => 'CA', 'country' => 'usa', 'zip' => '11111'));

$donor_data = $igf->donor->create($donor);

// Create a new Account for the Donor we just created
$account = new AccountInfo();
$account->setCreditCard('4111111111111111', '124', '02', '2023');
$account->setDonorInformation($donor_data['guid'], array('billingAddress1' => '123 Candy Lane', 'billingCity' => 'Imaginary', 'billingState' => 'CA', 'billingZip' => '11111'));

$account_data = $igf->account->create($account);

// Now create a donation. We've already picked out our nonprofit and publisher campaigns.
$donation = new DonationInfo();
$donation->setDonation('40.11', $nonprofit_campaign, $publisher_campaign, $account_data['guid'], $donor_data['guid']);

$donation_data = $igf->donation->create($donation);

// Finally, we can inspect the donation we just posted
$donation = $igf->donation->get($donation_data['guid']);
print_r($donation);

?>

iGivefirst REST捐赠API

为了使用iGivefirst捐赠API，您必须符合PCI级别1的要求

入门指南

为了使用iGivefirst捐赠API，您首先需要在我们网站上注册为发布者。

SDK前提条件 - 为了使用PHP SDK，您需要编译了OpenSSL支持的cURL扩展
注册为发布者 - 在 https://www.igivefirst.mobi/join/publisher 上注册
请求访问权限 - 发送电子邮件到 support@igivefirst.com 并提供您的账户信息，我们将为您设置访问权限
配置API密钥 - 访问API页面 https://www.igivefirst.mobi/publisher/donation-api 以获取您的API密钥并配置白名单IP地址。

指南

我们的API使用标准36字符guid形式的业务密钥。这些guid是在我们系统中创建的，并且是唯一的。以下是被主要使用的guid

非营利活动Guid - 这是非营利组织设置的活动的guid表示形式。此guid可以通过广告服务API访问，并且几乎用于所有API调用。
发布者活动Guid - 这是创建发布者活动时创建的guid。同样，此guid几乎用于每个调用。
捐赠者Guid - 这是捐赠者的唯一标识符
捐赠者账户Guid - 为了调用我们的API处理捐赠者的捐赠，使用捐赠者账户guid。

安全的REST捐赠API

获取私钥

以发布者身份登录并点击左下角的api链接。从那里，您将能够访问上述提到的所有guid。这还包括用于保护我们系统的两个密钥

发布者API密钥
发布者保密密钥

使用REST API进行请求认证

当使用REST访问iGivefirst API时，您必须在请求中提供以下项目以进行认证

请求元素

发布者API密钥 - 这是您用于发送请求的身份的访问密钥ID。
签名 - 每个请求必须包含有效的请求签名，否则请求将被拒绝。请求签名是使用您的发布者保密密钥计算的，这是只有您和iGivefirst知道的共享密钥。
时间戳 - 每个请求必须包含请求创建的日期和时间，表示为UTC字符串。时间戳的一个示例是：Thu, 18 Nov 2010 11:27:35 GMT。此时间戳必须与随附的HTTP日期标头匹配

授权

iGivefirst REST API使用标准的HTTPAuthorization标头传递认证信息。
以下是一个示例头

Authorization: IGF_HMAC_SHA1 59e680df-df0a-42c3-969a-800d35ca5684:frJIUN8DYpKDtOLCwo//yllqDzg=

标题由发布者API密钥和签名连接而成。

授权类型 - IGF_HMAC_SHA1
iGivefirst API密钥 - 59e680df-df0a-42c3-969a-800d35ca5684
签名 - frJIUN8DYpKDtOLCwo//yllqDzg=

签名是通过Base64编码的HMAC-SHA1（UTF-8编码的StringToSign，发布者密钥）计算得出的，其中

StringToSign = 
	HTTPVerb + "\n" 
	MD5-HASH-OF-Content + "\n" +
	Content-Type + "\n" +
	Timestamp + "\n" + 
	CanonicalizedResourceURI

StringToSign的示例

POST\n
bc1153d10db6079ecfbe3c3dca023402\n
application/json\n
Thu, 15 Sep 2012 00:51:48 GMT\n
/donation

或

GET\n
\n
\n
Thu, 15 Sep 2012 00:51:48 GMT\n
/donation/5def4c5f-e318-471f-9ef7-05cc965233cd

或

DELETE\n
\n
\n
Thu, 15 Sep 2012 00:51:48 GMT\n
/donation/5def4c5f-e318-471f-9ef7-05cc965233cd

然后使用StringToSign构建签名，方法如下：

对StringToSign进行UTF-8编码
使用您的密钥计算StringToSign的HMAC-SHA1
将结果哈希字节进行Base64编码，排除任何哈希的十六进制编码

一旦您有了签名，您通过连接访问密钥和签名来创建授权标题

Authorization: IGF_HMAC_SHA1 59e680df-df0a-42c3-969a-800d35ca5684:frJIUN8DYpKDtOLCwo//yllqDzg=

白名单IP地址

生产系统仅与您在API密钥设置期间列出的IP地址通信。

捐赠API端点

捐赠API用于创建、获取或删除捐赠。

使用的标题

内容类型：application/json
接受：application/json（适用时）
日期：Thu, 15 Sep 2012 00:51:48 GMT
Authorization: IGF_HMAC_SHA1 59e680df-df0a-42c3-969a-800d35ca5684:frJIUN8DYpKDtOLCwo//yllqDzg=

HTTP动词

GET - 获取捐赠

URI - /donation/:guid
返回 - 包含可选字段（如非营利组织名称）的完整JSON捐赠对象
成功代码 - 200
错误代码
- 500 输入错误
- 404 通过该guid未找到捐赠

示例

GET /donation/59e680df-df0a-42c3-969a-800d35ca5684
Accepts: application/json
Date: Tue, 27 Mar 2007 21:15:45 +0000
Authorization: IGF_HMAC_SHA1 59e680df-df0a-42c3-969a-800d35ca5684:frJIUN8DYpKDtOLCwo//yllqDzg=

响应

{
  "guid"                      :   "59e680df-df0a-42c3-969a-800d35ca5684",
  "amount"                    :   42.80,
  "sponsorMatchingPercentage" :   20, // optional
  "nonProfitCampaignGuid"     :   "8aec529c-dc93-4e5a-a02d-2965f16d327e",
  "publisherCampaignGuid"     :   "59e680df-df0a-42c3-969a-800d35ca5684",
  "sponsorCampaignGuid"       :   "ca712410-8e11-46a5-872c-de8ba7744e42", // optional
  "publisherTransactionId"    :   "42",  // optional provided by publisher
  "donorGuid"                 :   "ca712410-8e11-46a5-872c-de8ba7744e42",
  "status"                    : "NON_PROFIT_PAID", // various status codes - PENDING_BATCH, PUBLISHER_BATCH_COMPLETED, PUBLISHER_PAYMENT_ERROR, NONPROFIT_PAID, NONPROFIT_PAYMENT_ERROR, ON_HOLD, CANCELLED, EXCEPTION
  "dateCreated"               :   "2013-02-14:14:23:00Z", // ISO 3602 timestamp YYYY-MM-DDThh:mmZ GMT
  "publiserName":        : "Publisher Name",
  "nonProfitName":       : "Hobbit's for Humanity",
  "sponsorName" :        : "Thorin & Co." // optional
}

POST - 为捐赠者创建捐赠

URI: /donation
正文 - 捐赠对象
成功代码 - 201 created
错误代码
- 500 内部错误
- 400 完整的POST正文有误
- 401 未授权

示例

POST /donation
Accepts: application/json
Content-Type: application/json
Date: Tue, 27 Mar 2007 21:15:45 +0000
Authorization: IGF_HMAC_SHA1 59e680df-df0a-42c3-969a-800d35ca5684:frJIUN8DYpKDtOLCwo//yllqDzg=

正文

{
  "amount"                    :   42.80, // amount in USD
  "sponsorMatchingPercentage" :   20, // optional
  "nonProfitCampaignGuid"     :   "8aec529c-dc93-4e5a-a02d-2965f16d327e", 
  "publisherCampaignGuid"     :   "59e680df-df0a-42c3-969a-800d35ca5684",
  "sponsorCampaignGuid"       :   "ca712410-8e11-46a5-872c-de8ba7744e42", // optional
  "publisherTransactionId"    :   "42", // optional - supplied by the publisher
  "donorAccountGuid"          : "ca712410-8e11-46a5-872c-de8ba7744e432”
  "donorGuid"				  : "59e680df-df0a-42c3-969a-800d35ca5684"
}

响应成功

{
 "guid"                    :   "8aec529c-dc93-4e5a-a02d-2965f16d327e"
}

响应失败

{
 "errors"                    :   {"errors" : "Error messages"} // human readable error messages
}

DELETE - 取消捐赠

尚未实现

URI: /donation/:guid-of-donation
返回 - 捐赠的guid字符串
成功代码 - 201
错误代码
- 500 内部错误
- 401 未授权

示例

DELETE /donation/59e680df-df0a-42c3-969a-800d35ca5684
Date: Tue, 27 Mar 2007 21:15:45 +0000
Authorization: IGF_HMAC_SHA1 59e680df-df0a-42c3-969a-800d35ca5684:frJIUN8DYpKDtOLCwo//yllqDzg=

PUT - 未实现

使用DELETE取消捐赠，然后POST创建新的捐赠

错误代码 - 405 - 不允许的方法

捐赠者API端点

捐赠API用于查找、创建、获取或删除捐赠者。

使用的标题

内容类型：application/json
接受：application/json（适用时）
日期：Thu, 15 Sep 2012 00:51:48 GMT
Authorization: IGF_HMAC_SHA1 59e680df-df0a-42c3-969a-800d35ca5684:frJIUN8DYpKDtOLCwo//yllqDzg=

HTTP动词

GET - 查找捐赠者

URI - /find-donor
参数 - email - 捐赠者的电子邮件地址
返回 - 捐赠者JSON对象
成功代码 - 200
错误代码 - 404

示例

GET /find-donor?email=biblo@bagsend.com
Accepts: application/json
Date: Tue, 27 Mar 2007 21:15:45 +0000
Authorization: IGF_HMAC_SHA1 59e680df-df0a-42c3-969a-800d35ca5684:frJIUN8DYpKDtOLCwo//yllqDzg=

响应

{
   "firstName"         : "Frodo",
   "lastName"          : "Baggins",
   "sharePersonalInfo" : false,
   "contactInfo"       : {
    "cellPhoneNumber"   : "3035511234",
    "workPhoneNumber"   : "234134435",
    "homePhoneNumber"   : "1213",
    "billingAddress1"   : "123 Shire Blvd",
    "billingAddress2"   : "Lower Hobbit Hole",
    "billingCity"       : "The Shire",
    "billingState"      : "CO",
    "billingZip"        : "80125",
    "billingCountry"    : "US"
   },
   "email"             : "bilbo.baggins@gmail.com",
   "accounts"          : [ { active: true, guid: 59e680df-df0a-42c3-969a-800d35ca5684, displayInfomation: "Visa ending in 4358" } ],
   "anonymous"         : false
}

GET - 通过guid获取捐赠者

URI - /donor/{donor-guid}
返回 - 完整的JSON捐赠者对象。
成功代码 - 200
错误代码 - 404

示例

GET /donor/59e680df-df0a-42c3-969a-800d35ca5684
Accepts: application/json
Date: Tue, 27 Mar 2007 21:15:45 +0000
Authorization: IGF_HMAC_SHA1 59e680df-df0a-42c3-969a-800d35ca5684:frJIUN8DYpKDtOLCwo//yllqDzg=

响应

{
   "firstName"         : "Frodo",
   "lastName"          : "Baggins",
   "sharePersonalInfo" : false,
   "contactInfo"       : {
    "cellPhoneNumber"   : "3035511234",
    "workPhoneNumber"   : "234134435",
    "homePhoneNumber"   : "1213",
    "billingAddress1"   : "123 Shire Blvd",
    "billingAddress2"   : "Lower Hobbit Hole",
    "billingCity"       : "The Shire",
    "billingState"      : "CO",
    "billingZip"        : "80125",
    "billingCountry"    : "US"
   },
   "email"             : "bilbo.baggins@gmail.com",
   "accounts"          : [ { active: true, guid: 59e680df-df0a-42c3-969a-800d35ca5684, displayInfomation: "Visa ending in 4358" } ],
   "anonymous"         : false
}

POST - 创建捐赠者

URI - /donor
有效载荷 - 完整的JSON捐赠者对象。在有效载荷中不允许创建账户。
成功代码 - 202
错误代码
- 500 输入验证错误
- 405 该电子邮件地址已注册的用户

示例

POST /donor
Accepts: application/json
Date: Tue, 27 Mar 2007 21:15:45 +0000
Authorization: IGF_HMAC_SHA1 59e680df-df0a-42c3-969a-800d35ca5684:frJIUN8DYpKDtOLCwo//yllqDzg=

正文

{
   "firstName"         : "Frodo",
   "lastName"          : "Baggins",
   "billingAddress1"   : "123 Shire Blvd",
   "billingAddress2"   : "Lower Hobbit Hole",
   "city"              : "The Shire",
   "state"             : "CO",
   "zip"               : "80125",
   "country"           : "US",
   "cellPhoneNumber"   : "3035511234",
   "workPhoneNumber"   : "234134435",
   "homePhoneNumber"   : "1213",
   "username"          : "bilbo.baggins@gmail.com", *REQUIRED*
   "screenName"		   : "bilbo.baggins", *REQUIRED*
   "sharePersonalInfo" : true,
   "anonymous"         : false

}

响应

{ "guid" : "8aec529c-dc93-4e5a-a02d-2965f16d327e" }

PUT - 更新捐赠者

尚未实现

URI - /donor/{donor-guid}
有效载荷 - 完整的JSON捐赠者对象。在有效载荷中不允许更新账户。
成功代码 - 200
错误代码
- 500 输入验证错误

示例

PUT /donor/8aec529c-dc93-4e5a-a02d-2965f16d327e
Accepts: application/json
Date: Tue, 27 Mar 2007 21:15:45 +0000
Authorization: IGF_HMAC_SHA1 59e680df-df0a-42c3-969a-800d35ca5684:frJIUN8DYpKDtOLCwo//yllqDzg=

正文

{
   "firstName"         : "Frodo",
   "lastName"          : "Baggins",
   "sharePersonalInfo" : false,
   "contactInfo"       : {
    "billingAddress1"   : "123 Shire Blvd",
    "billingAddress2"   : "Lower Hobbit Hole",
    "billingCity"       : "The Shire",
    "billingState"      : "CO",
    "billingZip"        : "80125",
    "billingCountry"    : "US",
    "cellPhoneNumber"   : "3035511234",
    "workPhoneNumber"   : "234134435",
    "homePhoneNumber"   : "1213",
   },
   "username"             : "bilbo.baggins@gmail.com",
   "sharePersonalInfo" : true,
   "anonymous"         : false
}

DELETE

不支持

账户API端点

账户API用于创建或更新捐赠者账户。上面的捐赠者API为账户提供唯一的“获取”信息。

使用的标题

内容类型：application/json
接受：application/json（适用时）
日期：Thu, 15 Sep 2012 00:51:48 GMT
Authorization: IGF_HMAC_SHA1 59e680df-df0a-42c3-969a-800d35ca5684:frJIUN8DYpKDtOLCwo//yllqDzg=

HTTP动词

GET

不支持，可通过捐赠者API访问

POST - 创建捐赠者账户

URI - /account
有效载荷 - 完整的JSON账户对象 - 如果是信用卡账户，则包含信用卡信息，否则包含银行账户信息
成功代码 - 202
错误代码
- 500 输入验证错误

示例

POST /account
Accepts: application/json
Date: Tue, 27 Mar 2007 21:15:45 +0000
Authorization: IGF_HMAC_SHA1 59e680df-df0a-42c3-969a-800d35ca5684:frJIUN8DYpKDtOLCwo//yllqDzg=

正文

{
   "donorGuid"         : "59e680df-df0a-42c3-969a-800d35ca5684",
   "paymentMethod"     : "creditCard", // creditCard or ach allowed
   "creditCardNumber"  : "555555555555",
   "cwCode"            : 1234,
   "expirationMonth"   : "02",
   "expirationYear"    : 2023,
   "accountNumber"     : 4385589350,
   "routingNumber"     : 1234, 
   "accountHolderName" : "Biblo Baggins",
   "contactInfo"       : {
     "billingAddress1"   : "123 Shire Blvd",
     "billingAddress2"   : "Lower Hobbit Hole",
     "billingCity"       : "The Shire",
     "billingState"      : "CO",
     "billingZip"        : "80125",
     "billingCountry"    : "US"
   }
}

响应

{ "guid" : "8aec529c-dc93-4e5a-a02d-2965f16d327e" }

PUT - 更新账户

URI - /account/{account-guid}
有效载荷 - 完整的JSON账户对象
成功代码 - 200
错误代码
- 500 输入验证错误

示例

PUT /account/59e680df-df0a-42c3-969a-800d35ca5684
Accepts: application/json
Date: Tue, 27 Mar 2007 21:15:45 +0000
Authorization: IGF_HMAC_SHA1 59e680df-df0a-42c3-969a-800d35ca5684:frJIUN8DYpKDtOLCwo//yllqDzg=

正文

{
   "donorGuid"         :  "59e680df-df0a-42c3-969a-800d35ca5684",
   "paymentMethod"     : "cc", // cc or ach allowed
   "creditCardNumber"  : "555555555555",
   "cwCode"            : 1234,
   "expirationMonth"   : 02,
   "expirationYear"    : 2023,
   "accountNumber"     : 4385589350,
   "routingNumber"     : 1234, 
   "accountHolderName" : "Biblo Baggins",
   "paymentMethod"       : "ach", // ach or creditCard
   "contactInfo"       : {
     "billingAddress1"   : "123 Shire Blvd",
     "billingAddress2"   : "Lower Hobbit Hole",
     "billingCity"       : "The Shire",
     "billingState"      : "CO",
     "billingZip"        : "80125",
     "billingCountry"    : "US"
   }
}

响应

HTTP 200

DELETE - 禁用账户

URI - /account/{account-guid}
成功代码 - 202
错误代码
- 500 输入验证错误

示例

DELETE /account/59e680df-df0a-42c3-969a-800d35ca5684
Accepts: application/json
Date: Tue, 27 Mar 2007 21:15:45 +0000
Authorization: IGF_HMAC_SHA1 59e680df-df0a-42c3-969a-800d35ca5684:frJIUN8DYpKDtOLCwo//yllqDzg=

响应

HTTP 202

igivefirst / igf-sdk-php

维护者

详细信息

README

示例用法

iGivefirst REST捐赠API

入门指南

指南

安全的REST捐赠API

获取私钥

使用REST API进行请求认证

请求元素

授权

白名单IP地址

捐赠API端点

使用的标题

HTTP动词

GET - 获取捐赠

POST - 为捐赠者创建捐赠

DELETE - 取消捐赠

PUT - 未实现

捐赠者API端点

使用的标题

HTTP动词

GET - 查找捐赠者

GET - 通过guid获取捐赠者

POST - 创建捐赠者

PUT - 更新捐赠者

DELETE

账户API端点

使用的标题

HTTP动词

GET

POST - 创建捐赠者账户

PUT - 更新账户

DELETE - 禁用账户